One brain. Every agent. Nothing forgotten.

What is Aperio?

Aperio keeps memories, conversations, and knowledge available to your AI agents. It runs locally by default, stores data in SQLite, and exposes the same memory through a web UI, terminal chat, and MCP-compatible tools.

Quick start

Easiest: Aperio-lite

For a guided installation, download Aperio-lite, unzip it, and double-click START.

From source

Requirements: Node.js 18+. Docker is optional; SQLite is the default and needs no separate database server.

git clone --depth 1 -b dev https://github.com/BaiGanio/aperio.git
cd aperio
npm install
npm run start:local

Open http://localhost:31337 when the server is ready.

On first use, Aperio downloads the local AI engine and model. This may take a few minutes and several gigabytes of disk space. You do not need to install llama.cpp separately.

That is enough for a private local setup. The Web UI can configure most other settings after startup.

Optional configuration

To configure a provider before starting, create .env from the example:

cp .env.example .env

Then set the values you need, for example:

AI_PROVIDER=llamacpp
LLAMACPP_MODEL=unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL

Cloud providers require their own API key. Postgres, cloud embeddings, code/doc graphs, encryption, path permissions, browser access, and other advanced options are documented in the advanced guide and the Aperio Wiki.

Terminal chat

Prefer a terminal? Start a second interface with:

npm run chat:local

It uses the same database and memories as the Web UI.

MCP and integrations

Aperio exposes memory, wiki, file, code-graph, document, and other tools over MCP. See the MCP Tools Guide for connection instructions and examples.

Help

Contributing

npm test

Read the testing guide and the contributor/developer notes before changing the runtime, database, configuration, or agent loop.

The id/ folder is where Aperio's own coding agents keep their working notes: reference docs, plus small "identity" files (whoami.md, self-nature.md, characters/) that shape how they behave. It is not user-facing — safe to ignore unless you're curious how the agents that build Aperio are set up.

License

MIT