baiganio/aperio

1. Aperio is a self-hosted Node.js memory layer for agents, not a standalone chat product. The core runtime exposes three faces over the same backend: a browser UI, a terminal chat client, and an MCP server for external tools and IDE agents.

2. server.js is the main app entrypoint. It ties together the HTTP API, WebSocket streaming, the agent loop, and the web UI in public/. The MCP server lives separately in mcp/index.js, so remote agents can use the same memory and code tools without going through the UI.

3. Persistence is centralized in db/. db/index.js auto-selects SQLite or Postgres, with SQLite as the default single-file store and Postgres used when Docker/production mode is available. Both backends share the same logical schema via migrations, and the store holds memories, wiki articles, code graph data, and embeddings metadata.

4. The memory subsystem is the main semantic store. lib/handlers/memory/ implements remember/recall/update/forget flows, while lib/helpers/embeddings.js, lib/helpers/embedding-queue.js, and lib/workers/deduplicate.js handle vectorization, backfilling, and near-duplicate cleanup. Semantic search is paired with full-text search in the database.

5. The wiki subsystem is a second knowledge layer, distinct from raw memories. lib/handlers/wiki/ supports article creation, search, retrieval, and regeneration, so the agent can maintain longer-form, cited synthesis rather than only short memory records. It uses the same backing store but a different retrieval and authoring path.

6. Aperio’s code graph is a pre-indexed source knowledge system. lib/codegraph/ extracts symbols, calls, imports, and inheritance edges from code, using tree-sitter-based extractors for JS/TS/JSX/TSX and watcher-driven incremental reindexing. The code_* MCP tools query this graph for callers, callees, outlines, and symbol context.

7. The document graph complements the code graph for non-code files. lib/docgraph/ and lib/handlers/docgraph/ ingest PDFs, DOCX, PPTX, XLSX, HTML, EML, and Markdown, chunk them, extract references, and store them for search. Attachment preprocessing workers normalize PDFs and images before they are handed to local vision or extraction steps.

8. Agent behavior is orchestrated in lib/agent/, lib/workers/, and lib/tools/. Model providers are pluggable: Ollama is the local default, with Anthropic, DeepSeek, and Gemini supported as cloud alternatives. The agent layer also manages tool hooks, tool profiles, reasoning/roundtable workers, and context trimming via lib/context/.

9. The UI layer is a static frontend in public/ with panels for sessions, settings, wiki, code graph, database status, and streaming activity. It talks to the backend through API calls and WebSocket events, and the same stream is also surfaced in the terminal client through emitter abstractions in lib/emitters/.

10. Security is enforced at the path boundary, not inside the model. lib/routes/paths.js validates read/write locations against allow-lists, and shell execution is heavily gated in mcp/tools/shell.js. The default execution model is conservative: file access is scoped, writes are restricted, and shell commands are opt-in and allow-listed.

11. There is an optional two-agent “roundtable” path. When configured, a primary and verifier persona from id/whoami-primary.md and id/whoami-verifier.md can cross-review a turn before the result is returned, with the UI exposing a Discuss toggle and the backend running the revise/re-review loop in lib/workers/roundtable.js.

12. The skills/ directory is not a runtime service; it is a library of task-specific playbooks and assets that shape how agents behave and how certain document/code generation workflows are performed. In architecture terms, it is an instruction and tooling layer wrapped around the same core memory/graph backend.