Features

Everything you need.
Nothing you don't.

Built for developers who want AI that actually knows them. Without giving up their data or their infrastructure.

Persistent Memory

Your memories survive every conversation, every tool, every session. 9 structured types keep things organized — facts, preferences, decisions, solutions and more. Three sensitivity tiers keep your private data safe: tier 1 shared as-is, tier 2 PII-redacted on cloud, tier 3 never leaves your machine.

Agent Self-Memory

The AI keeps its own private notebook — walled off from your memories. It learns what works, remembers your style, and carries its own observations across every session.

Semantic Search

Powered by on-device embeddings (mxbai-embed-large) over sqlite-vec or pgvector. Ask about your projects and get results matched by meaning, not keywords. Voyage AI optional.

MCP Native

One brain shared across every agent. Claude, Cursor, Windsurf — all connect to the same Postgres database through the MCP protocol.

Real-time Streaming

Responses stream token by token via WebSocket. Live code rendering, markdown on completion, smart auto-scroll. No waiting.

Local by Default

Runs fully on your machine with llama.cpp — free, private, offline-capable. Switch to Claude with one env variable when you need more power.

Auto Deduplication

Background job finds near-duplicate memories every 10 minutes using cosine similarity. Dry-run by default — you stay in control.

Reasoning Models

Native support for thinking models like qwen3, gemma4 and llama3 — and cloud models reason out of the box. A collapsible reasoning bubble shows the model's thought process live. Toggle it on or off anytime.

Two-Agent Deliberation

Toggle Discuss and two agents cross-review each other until they agree. Domain characters give each a different perspective.

learn more...

Talk to Your Database

Connect SQLite, Postgres or MySQL and ask in plain English. Aperio writes the SQL — reads run instantly, and any change to your data asks you to confirm first.

learn more...

Team Ready coming soon

Since you own the database, Aperio scales from personal to shared team brain with two changes — update the system prompt and seed team memories. One brain for the whole team.

Architecture

Simple stack. Serious power.

One database. One MCP server. Two AI providers. Your brain is just a Postgres table with vectors.

aperio / system architecture

🌐

Web UI

localhost:31337 · 4 themes · streaming

↕ WebSocket

⚡

Express Server

server.js · agent loop

↕ stdio

🔧

MCP Server

mcp/index.js · 54 tools · 12 categories

↕

🐘

SQLite (default) · Postgres 16 + pgvector

sqlite-vec · pgvector · HNSW index

↕

⬡

Local Embeddings

mxbai-embed-large-v1 · 1024 dims · zero external calls

✦

Voyage AI

optional · voyage-3 · 1024 dims · cloud upgrade

AI Providers

⬡

llama.cpp

default · local · free · offline capable

✦

Claude · Gemini · DeepSeek

optional · cloud APIs

🤖

Claude Code · Codex CLI

optional · coding agents

Memory Types

factpreference projectdecision solutionsourcepersoninferenceworkflow

MCP Tools

54 tools. One protocol.

Each one is available to any MCP-compatible agent (Claude, Cursor, Windsurf).

Memory6 tools

remember

Save a new memory — auto-generates embedding for semantic retrieval

remember

Remember that we deploy to production on Tuesdays only, and never after 4pm.

recall

Semantic search with cosine similarity, FTS fallback

recall

What did we decide about rate limiting on the public API?

update_memory

Edit by UUID — new version, old tombstoned

update_memory

Update the memory about our staging URL — it moved to staging.internal.acme.dev.

forget

Delete a specific memory by UUID

forget

Forget the note about the old Redis credentials — that setup is gone.

backfill_embeddings

Batch-generate embeddings for unembedded memories

backfill_embeddings

Some older notes aren't showing up in semantic search — generate the missing embeddings.

deduplicate_memories

Find near-duplicates via cosine similarity

deduplicate_memories

I've saved that deploy note three times. Find the near-duplicates and show me before deleting anything.

Self-Memory4 tools

self_remember

Agent saves a note to its own private store — walled off from user memories

self_remember

Note down for yourself how I like commit messages written, so you don't have to ask me again.

self_recall

Agent searches its own notes semantically or by full-text

self_recall

Before you start, check your own notes on how this repo's tests are usually run.

self_update

Agent revises one of its own notes in-place

self_update

Your note about my timezone is stale — I moved to UTC+3. Fix your own record.

self_forget

Agent deletes one of its own notes

self_forget

Drop your note about preferring tabs — we moved that repo to spaces months ago.

Files9 tools

read_file

Read any file from disk (max 500 lines)

read_file

Open lib/config.js and explain what the precedence chain actually does.

write_file

Create or overwrite a file

write_file

Write a fresh docker-compose.yml for a Postgres 16 + pgvector setup under ./infra.

append_file

Append content to end of file

append_file

Append today's decisions to the bottom of NOTES.md, dated.

edit_file

Search-and-replace in an existing file

edit_file

In server.js, make every hardcoded port 3000 read from process.env.PORT instead.

read_docx

Read and extract text from .docx files

read_docx

Read the requirements.docx the client sent and list every hard requirement as bullets.

scan_project

Scan folder tree up to 3 levels deep

scan_project

Scan this repo three levels deep and tell me where the auth code actually lives.

delete_file

Delete a file by path

delete_file

Delete the leftover config.old.json — but check nothing references it first.

generate_xlsx

Create Excel spreadsheets from data

generate_xlsx

Turn last month's invoice list into an .xlsx with one sheet per client.

generate_docx

Create Word documents programmatically

generate_docx

Draft the release notes as a .docx I can send to the non-technical stakeholders.

Wiki4 tools

wiki_write

Create or update a cited wiki article from memories

wiki_write

Write up everything we know about the billing pipeline as a wiki article, and cite the memories you used.

wiki_search

Hybrid FTS + semantic search across wiki articles

wiki_search

Search the wiki for anything we've written about incident postmortems.

wiki_list

Browse wiki articles, newest first

wiki_list

What wiki articles do we have, newest first? I want to see what has gone stale.

wiki_get

Fetch a wiki article by slug with revision info

wiki_get

Pull up the 'deploy-process' article and tell me when it was last revised.

Code Graph6 tools

code_search

Search indexed code symbols by name or doc text

code_search

Find every symbol whose name or docs mention 'embedding queue'.

code_repos

List all indexed repos with symbol counts

code_repos

Which repos are indexed right now, and how many symbols does each one have?

code_outline

List every symbol in a file with line ranges

code_outline

Give me the outline of lib/agent/index.js — every function with its line range.

code_context

Fetch source slice for a symbol by qualified name

code_context

Show me the source of AgentOrchestrator.runTurn so I can see what it actually does.

code_callers

Find symbols that call the given target

code_callers

Who calls validatePath? I want the blast radius before I change its signature.

code_callees

Find symbols called by the given target

code_callees

What does startLlamaCpp call internally? Trace one level down.

Doc Graph5 tools

doc_search

Search indexed document passages by meaning

doc_search

Search our documents for the passage about data retention obligations.

doc_repos

List all indexed doc folders with chunk counts

doc_repos

Which document folders are indexed, and how many chunks does each hold?

doc_outline

Section tree (TOC) for one document

doc_outline

Show me the section tree of the vendor contract PDF.

doc_context

Fetch text of one section or chunk

doc_context

Fetch the full text of section 7.2 from that contract.

doc_refs

Cross-document reference lookup (IDs, URLs, citations)

doc_refs

Which of our documents reference invoice INV-2024-0912?

Shell4 tools

run_node_script

Execute Node.js scripts in a sandbox

run_node_script

Write and run a quick Node script that counts the rows per table in that SQLite file.

run_python_script

Execute Python scripts in a sandbox

run_python_script

Run a Python script to chart last week's latency numbers from this CSV.

syntax_check

Validate code syntax for supported languages

syntax_check

Check that the file you just edited still parses before we commit it.

run_shell

Execute shell commands with output capture

run_shell

Run the test suite and show me only the failures.

Web2 tools

fetch_url

Fetch a URL, strip HTML, truncate to 15k chars

fetch_url

Fetch that changelog URL and tell me whether anything in it breaks the version we pin.

web_search

Search the web via DuckDuckGo, return ranked results

web_search

Search the web for the currently recommended way to pin pgvector on Postgres 16.

Image3 tools

read_image

Read and OCR-extract text from images

read_image

Read this screenshot of the error dialog and tell me what the stack trace says.

preprocess_image

Optimize image for local vision models

preprocess_image

This scan is too big for the local vision model — optimize it before you read it.

describe_image

Generate a text description of an image

describe_image

Describe what's in this dashboard screenshot so I can paste it into the report.

GitHub5 tools

fetch_github_issue

Read a GitHub issue with comments and metadata

fetch_github_issue

Read issue #327 with all its comments and summarize what is actually blocking it.

create_github_issue

Open a new issue on a GitHub repository

create_github_issue

Open an issue for that flaky path test — include the failure output and a repro.

update_github_issue

Edit an existing GitHub issue

update_github_issue

Update issue #290 with the workaround we found and re-label it as confirmed.

list_github_issues

List open issues for triage across repos

list_github_issues

List the open issues across our repos so we can triage them this morning.

record_issue_triage

Record a triage verdict for an issue

record_issue_triage

Record my verdict on #312: won't fix, superseded by the new config layer.

Data2 tools

export_data

Export memories & wiki to a portable JSON file

export_data

Export all memories and wiki articles to a JSON file I can back up.

import_data

Import memories & wiki from an export file

import_data

Import the export from my old laptop and tell me what got merged and what was skipped.

Database4 tools

db_connections

List available database connections (never exposes credentials)

db_connections

Which databases can you reach right now?

db_schema

Introspect tables, columns, indexes, and foreign keys

db_schema

Show me the schema of the orders table — columns, indexes and foreign keys.

db_query

Run ONE read-only SQL statement with parameterized bindings

db_query

How many orders were placed last week, grouped by status?

db_execute

Propose a write/DDL statement — confirm-before-write flow

db_execute

Add a nullable 'cancelled_at' column to orders — show me the SQL before you run it.

Team Ready out of the box

Personal memories.
Or shared team memories.
You decide.

Aperio is personal by default.
But since you own the database, it can become a shared team brain with minimal changes.
Every agent, every teammate, every tool — all drawing from the same memory pool.

📋

Shared Decisions

Six months later, nobody remembers why you picked one vendor over the other. The Slack thread is archived, the RFC was never written — and the same debate starts again from zero.

See the prompt

Everyday prompt

Before we move the billing workers off Fly.io — pull everything we've stored about that hosting decision. Why did we choose Fly over Railway, what cost assumptions did we make, and which of those still hold now that we run three always-on services?

Back

🗂️

Project Knowledge

Every project has a stack, an owner and a dozen unwritten conventions that live in one person's head. Each context switch turns into an archaeology dig.

See the prompt

Everyday prompt

I'm picking up a ticket on Project Atlas and I haven't touched it in two months. Remind me of the stack, who owns which part, the conventions we agreed on for migrations, and anything we decided never to do again in that repo.

Back

🚀

Onboarding

A new teammate joins and the same twenty questions get answered for the fifth time — in DMs, out of band, slightly differently every time.

See the prompt

Everyday prompt

A new backend dev starts Monday. Draft their first-week guide from our team memory: which repos they need, what access to request and from whom, how our deploy flow actually works, and the three gotchas that bite everyone in week one.

Back

📖

Runbooks

It's 2am, production is down, and the one person who remembers the recovery order is asleep, on a plane, or no longer at the company.

See the prompt

Everyday prompt

Postgres connections are maxed out in production and the API is timing out. Walk me through our recovery runbook step by step — and tell me whether we've hit this before, what actually fixed it last time, and what we said we'd change afterwards.

Back

👥

People Context

Knowing who to ask — and how they prefer to be asked — is half the job. That knowledge usually lives nowhere except in the habits of whoever has been here longest.

See the prompt

Everyday prompt

I need a decision on the analytics schema by Thursday. Who owns that area, which timezone are they in, do they prefer async or a call — and has anyone already raised concerns about this schema that I should read before I ask?

Back

🔍

Cross-Project Search

Some questions span every repo you own — "where else do we do this?" No single codebase can answer them, and no one has time to check them all.

See the prompt

Everyday prompt

Stripe is deprecating the API version we pin. Search across every project in memory: which ones integrate Stripe, which version each one pins, who owns them, and what we'd have to touch to upgrade each.

Back

team setup — 2 changes only

1. Update id/whoami.md

You are a helpful team assistant with access to Aperio
— a shared memory system that stores context
about your team, projects, and decisions.

2. Seed team memories in 001_init.sql

INSERT INTO memories (type, title, content)
VALUES
  ('project', 'Atlas', 'Next.js + PlanetScale...'),
  ('person', 'Sara', 'PM for Atlas...'),
  ('decision', 'Fly.io', 'Chosen Q3 2024...');

Extensibility

Build on top.
Make it yours.

Aperio is a foundation, not a finished product. The source is fully open — fork it, extend it, repurpose it.
Here's what you can build on top.

Memory Layer

Custom Memory Types

The schema is yours to extend. Add new memory types, extra metadata columns, TTL logic, or per-project namespacing. Postgres gives you full flexibility.

mood_log habit_tracker meeting_note code_snippet bookmark

MCP Layer

New MCP Tools

Adding a tool is just a new entry in mcp/index.js. Expose calendar access, email drafting, browser control — any action you want your agents to take.

calendar_tool send_email run_tests git_commit deploy

AI Layer

Swap the Embedding Model

mxbai-embed-large runs on-device via transformers by default — zero external calls. Swap in Voyage AI for higher quality, or drop in OpenAI, Cohere, or any provider with a vectors API.

openai/text-embedding-3 cohere-embed nomic-embed-text

UI Layer

Replace or Extend the UI

The web interface is a standalone HTML file with WebSocket. Rip it out and build a VS Code extension, a mobile app, a CLI, a Chrome sidebar — the server API stays the same.

vscode extension raycast plugin mobile app chrome sidebar

Data Layer

Memory Analytics & Insights

Query your own memory graph. Build dashboards showing what topics you think about most, decision patterns over time, knowledge gaps, or memory growth by week.

knowledge graph memory heatmap topic clusters decay scoring

Team Layer

Team Shared Memory

Since you own the database, Aperio scales from personal to team brain with two changes: update the system prompt to team context, seed team memories in 001_init.sql.

shared decisions project knowledge onboarding runbooks

Agent Layer

Multi-Agent Memory Sharing

Run multiple specialized agents that all share one brain. A research agent stores findings, a coding agent reads context, a writing agent pulls preferences — all from the same database.

research agent coding agent shared context team memory

Agent Layer

Background Agents

Scheduled, autonomous agents that run without a chat turn. Define jobs in the database, set interval or file-watcher triggers, and let them handle deduplication, wiki refresh, code indexing — silently, in the background.

scheduled jobs file watchers auto dedup wiki refresh

Got an idea? Build it and share it.

Open a PR, open an issue, or fork it and take it somewhere new. Aperio is a starting point.

Fork on GitHub

Why Aperio

Your data. Your rules.

Commercial memory services are great products.
Aperio is a different choice — self-hosted, open source, fully customizable.

Feature	✦ Aperio	Cloud Services
Data ownership	✅ 100% yours — own Postgres	✗ Vendor's servers
Monthly cost	✅ Free (self-hosted)	✗ $20–100 / month
Local AI support	✅ llama.cpp built-in	✗ Cloud only
File system tools	✅ read · write · append	✗ Not available
Full source access	✅ Open source — fork it	✗ Closed API
MCP integration	✅ Native protocol	⚠ Varies
Works offline	✅ With llama.cpp	✗ Requires internet
Non-developer friendly	✅ Aperio-lite — double-click & go	✗ Requires dev setup
Team memory	✅ Shared DB — one brain for the team	⚠ Varies by plan

Web UI

See it in action.

Local AI · persistent memory · streaming responses · 4 themes.

Quick Start

Up in 5 minutes.

Three ways in — pick your comfort level. Everything runs 100% local by default: no API keys, no cloud.

1 · Aperio-lite

No code, no terminal. Download → unzip → double-click. A browser wizard installs everything and picks a model that fits your machine.

Jump to the lite guide →

2 · One command

# clones the release branch → starts Aperio

curl -fsSL https://raw.githubusercontent.com/BaiGanio/aperio/release/.github/lite/install.sh | bash

# re-run anytime to update in place —

# your memory database is preserved

3 · From source

Full control — clone the dev branch and run it yourself. Node 24+; SQLite by default, Postgres optional. Step-by-step below.

Method 3 · From source

Clone & install dependencies

# dedicated developer branch - no extra files

git clone --depth 1 -b dev https://github.com/BaiGanio/aperio.git

cd aperio

# install dependencies

npm install

Ready for use .env.example in the project folder

AI_PROVIDER=llamacpp
LLAMACPP_MODEL=unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL
EMBEDDING_PROVIDER=transformers
# DB_BACKEND auto-detects: SQLite (default) or Postgres
# DATABASE_URL=postgresql://…  — only if you choose Postgres

Databases

# default: SQLite + sqlite-vec — nothing to install

npm run migrate:sqlite

# optional: Postgres + pgvector instead

cd docker && docker compose up -d && cd ..

npm run migrate

Pick a model — nothing to install

# Aperio vendors + starts the llama.cpp engine itself — downloads the model on first use

Available options:

default - unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL (up to 8 GiB RAM, ~2.6 GB disk) ★ recommended

medium - ggml-org/gemma-4-E4B-it-GGUF:Q4_K_M (~8GB RAM, ~5GB disk)

smart - ggml-org/gemma-4-12B-it-GGUF:Q4_K_M (~24GB RAM, ~8GB disk)

reasoning - Qwen/Qwen3-30B-A3B-GGUF:Q4_K_M (~48GB RAM, or fast-low-vram profile, ~18GB disk)

# embeddings run on-device (transformers) — no model to pull

Launch Aperio Web UI

# start from the project root

# opens at localhost:31337

npm run start:local

# cloud (Claude) -> localhost:3000

# npm run start:cloud

Use Aperio chat in the terminal

# local (llama.cpp)

# auto-detect if any Docker - uses SQLite as fallback

npm run chat:local

# cloud (Anthropic)

npm run chat:cloud

✅ Tip: Check out project README.md for extensive documentation, troubleshooting, and advanced configuration options.

Aperio-lite · For non-code humans

Small tool. Big ideas. 🧐
No coding skills required.

The fastest path to your own private AI.
Runs 100% on your machine. No Money. No Cloud. No register your email here and there.
Download → unzip → double-click. That's it.

Double-click Launch macOS Linux Windows Delete to uninstall

the whole flow — once is enough

📥 Download → 📂 Unzip → 🔗 Make Alias / Shortcut → 🖥️ Drop on Desktop → Double-click → (one-time) setup → Browser opens automatically

macOS

Download, unzip, open in Finder
START.sh is right at the top level (the how-to folder holds a printable guide)
Find START.sh → right-click → Make Alias
Rename the alias to Aperio
A Drag alias to Desktop folder in Finder's sidebar
❗ Sidebar item — not the Desktop surface itself
B Hold ⌥ Option + ⌘ Cmd and drag START.sh directly onto the desktop → rename it there
Double-click → one-time setup → done
✅ Default browser opens automatically at
http://localhost:31337

Windows

Download, unzip, open in File Explorer
START.bat is right at the top level (the how-to folder holds a printable guide)
Find START.bat → right-click → Rename
Rename the file to Aperio.bat
A Move shortcut to Desktop
B Hold Alt and drag START.bat directly onto the desktop → rename it there
Double-click → one-time setup → done
✅ Default browser opens automatically at
 http://localhost:31337

Linux

1. Download, unzip, open in your file manager
2. START.sh is right at the top level (the how-to folder holds a printable guide)
3. Find START.sh → right-click → Properties → Permissions
4. Enable Allow executing file as program → close
5. Right-click START.sh → Copy to Desktop → rename to Aperio
❗ Menu labels vary by distro (Nautilus, Dolphin, etc.)
6. Double-click → one-time setup → done
✅ Default browser opens automatically at
 http://localhost:31337

No tech skills required

Nothing to configure.
✅ No databases to set up.
✅ No config files to edit.
✅ No environment variables.
✅ No package managers.
Just download and double-click.
First run installs everything automatically in the background.
You'll see a terminal window — that's normal.
 The terminal is yours GOD EYE on what is happening.

Feature updates

Download the latest release.
✅ Windows
- Right-click on the zip and select "Extract All..."
- In the dialog, specify your aperio-lite folder.
✅ macOS/Linux (Terminal - fastest)
- unzip aperio-lite.zip -d ~/aperio-lite
Installed with the one-liner? Even easier.
Re-run the install command (or git pull in the folder) — it fast-forwards to the latest release and keeps your memory database. No re-download.
Your data stays untouched.
❗ Might want to export your memories first.
- You'll have your data even if the update fails

subsequent runs & Uninstall

Every run after the first run?
Double-click the desktop shortcut. That's it.
Terminal: bash START.sh
✅ If you can open a browser, you can run Aperio.
How to remove it if I do not like it?
1. Delete the Desktop alias / shortcut
2. Delete the unzipped folder
✅ That's it. Completely gone.
- No registry entries. No hidden files.
- No traces. Nothing.

Download Aperio-lite I prefer the terminal

Every memory. Any agent.
Total recall.

Everything you need.
Nothing you don't.

Simple stack. Serious power.

54 tools. One protocol.

Personal memories.
Or shared team memories.
You decide.

Build on top.
Make it yours.

Your data. Your rules.

See it in action.

Up in 5 minutes.

Small tool. Big ideas. 🧐
No coding skills required.

Your AI has been
amnesiac?
Fix that today.

Choose your language

Every memory. Any agent.Total recall.

Everything you need.Nothing you don't.

Simple stack. Serious power.

54 tools. One protocol.

Personal memories.Or shared team memories.You decide.

Build on top.Make it yours.

Your data. Your rules.

See it in action.

Up in 5 minutes.

Small tool. Big ideas. 🧐No coding skills required.

Your AI has beenamnesiac?Fix that today.

Choose your language

Every memory. Any agent.
Total recall.

Everything you need.
Nothing you don't.

Personal memories.
Or shared team memories.
You decide.

Build on top.
Make it yours.

Small tool. Big ideas. 🧐
No coding skills required.

Your AI has been
amnesiac?
Fix that today.