Skip to content

Home

Jump to bottom
Lyuben Kikov edited this page Jul 20, 2026 · 39 revisions

✨ Aperio Wiki

One brain. Every agent. Nothing forgotten.

Aperio is a self-hosted personal memory layer for AI agents. It gives your agents persistent memory, a wiki, code graph, and document graph — so they actually remember things across sessions, tools, and teammates.

🚧 This wiki is actively maintained. Pages are updated with each release.

Quick facts
Latest version v0.67.5
Default port :31337
Default AI provider llamacpp (vendored — no install needed)
Default embeddings @huggingface/transformers (local — no API key)
Default database SQLite (var/aperio.db) — zero-config
Alt database Postgres + pgvector (Docker)
MCP tools 38 tools across 13 modules
License MIT

Where do you want to start?

AI Providers

Aperio supports 6 AI providers:

Provider Type Default model
llamacpp (vendored) Local Qwen/Qwen2.5-3B-Instruct-GGUF (or configure your own)
Anthropic Cloud claude-haiku-4-5-20251001
DeepSeek Cloud deepseek-v4-flash
Gemini Cloud gemini-2.0-flash
Claude Code CLI claude (system install)
Codex CLI CLI OpenAI Codex

Set AI_PROVIDER in .env or the Settings overlay. Cloud providers need their respective API keys.

Storage

Backend Default Requires
SQLite + sqlite-vec + FTS5 ✅ Default Nothing — single file at var/aperio.db
Postgres + pgvector Optional Docker or hosted provider

Auto-detected: uses Postgres when Docker is running, SQLite otherwise. Force with DB_BACKEND=sqlite or DB_BACKEND=postgres.

MCP Tools (38 total)

Category Tools Module
Memory remember, recall, forget, update_memory, backfill_embeddings, deduplicate_memories, propose_memory memory.js
Self-memory self_remember, self_recall, self_update, self_forget self-memory.js
Self-wiki self_wiki_write, self_wiki_get self-wiki.js
Files read_file, grep_files, write_file, edit_file, append_file, delete_file, read_docx, scan_project, generate_xlsx, generate_docx files.js
Web fetch_url, web_search web.js
Image read_image, preprocess_image, describe_image image.js
Shell run_shell, run_node_script, run_python_script, syntax_check shell.js
Wiki wiki_get, wiki_write, wiki_search, wiki_list, propose_wiki wiki.js
Code graph code_search, code_context, code_outline, code_callers, code_callees, code_repos codegraph.js
Doc graph doc_search, doc_context, doc_outline, doc_refs, doc_repos docgraph.js
GitHub fetch_github_issue, create_github_issue, update_github_issue, list_github_issues, record_issue_triage github.js
Data export_data, import_data data.js
Database db_query, db_execute, db_schema, db_connections database.js

Features at a glance

  • Persistent memory — 7 structured types (fact, preference, project, decision, solution, source, person)
  • Semantic search — vector embeddings via transformers.js or Voyage AI
  • Full-text search — SQLite FTS5 or Postgres tsvector fallback
  • Wiki — persistent articles with hybrid search, auto-refresh
  • Code graph — tree-sitter index of your repos (symbols, callers, callees)
  • Document graph — full-text + vector index of notes, docs, PDFs
  • Round-table mode — two-agent cross-review for critical answers
  • Real-time streaming — SSE + WebSocket to browser
  • Auto-deduplication — background job finds near-duplicate memories
  • Brain export/import — portable JSON
  • 4 themes — Light · Dark · Aurora · System
  • Settings overlay — full configuration UI (no .env editing needed for most settings)
  • i18n — 26 languages (24 EU + Chinese + Japanese)
  • AES-256-GCM encryption — optional, keychain-backed

Architecture

Browser / Terminal / MCP host
  │
  ├─ Web UI ──────────► server.js (Express + WebSocket on :31337)
  │
  ├─ Terminal ────────► lib/terminal.js
  │
  └─ MCP host ───────► mcp/index.js (stdio transport)
                          │
                   ┌──────┴──────┐
                   ▼              ▼
             lib/handlers/   lib/agent/
             (WS routing)    (orchestrator)
                   │              │
                   ▼              ▼
             lib/streaming/  lib/context/   lib/agent/providers/
             (SSE + WS)      (prompts,      (Anthropic, llama.cpp,
                              memories,      DeepSeek, Gemini,
                              skills)        Claude Code, Codex)
                                    │
                                    ▼
                              mcp/tools/
                              (38 tools)
                                    │
                                    ▼
                              db/ (SQLite or Postgres)

See Architecture & Design discussion for deep-dive explanations.

Links

✨ Aperio • Developed by (BG) Team • 💬 Join Discussion

✨ Aperio • v0.67.5 • 💬 Join Discussion

✨ Aperio · Quick Links
🏠 Home
📖 README
🛠️ Troubleshooting
🚀 Roadmap
🔸 FAQ
🥇 LEADERBOARD

Getting Started

Core Features

Build On Top

Clone this wiki locally