Axon: per-project memory for AI agents
Durable facts about a codebase, kept for your agents behind an MCP server and a REST API, with pgvector search. Private to its project. About $42.38 a month.
Axon stores small facts about a codebase (its architecture, decisions, conventions and gotchas) and gives them back cheaply: a briefing at the start of a session, and hybrid semantic and keyword search after that. Its code is its own repository, not a directory of the recipes one.
What you build
Axon has no authentication of its own: anything that can reach its port
can read and write every project's memories. So this recipe runs it private,
with no address. A service of yours in the same project reaches it once it
declares the edge, and calls http://server:7717/mcp or /v1.
The server is size m because its embedding model, baked into the image so it starts offline, takes most of a gigabyte. At size s it is killed for memory.
Before you start
You need an ENCRYPTION_KEY (openssl rand -base64 32). Keep a copy
somewhere safe: without it, encrypted memories cannot be read.
DEPLOY.md also
covers a bearer-token gateway, for reaching axon from outside the project.
What Gagarin creates
| Name | Kind | Size | Holds |
|---|---|---|---|
database | postgres | s, 10 GB disk | the memories, with pgvector |
axon | external | none | ENCRYPTION_KEY and MAX_MEMORIES |
server | service | m | axon itself, private |
The commands
There is nothing to build: every commit to axon's main publishes an image to
Docker Hub tagged sha-<commit>, and the commands copy one in.
gg init axon
gg resource add axon/database postgres --storage 10 --ext vector
umask 077
printf 'ENCRYPTION_KEY=%s\nMAX_MEMORIES=5000\n' "$(openssl rand -base64 32)" > .env.axon
gg resource add axon/axon external --env-file .env.axon
AXON_TAG=sha-<commit>
gg registry copy axon/axon:$AXON_TAG docker.io/gagarincloud/axon:$AXON_TAG
gg deploy axon/server:7717 axon:$AXON_TAG --size m --deps database --deps axonThe database resource publishes DATABASE_URL, which axon reads as is, and
the axon external publishes AXON_ENCRYPTION_KEY and AXON_MAX_MEMORIES.
Migrations run when the server starts. A service of yours in the project
reaches it after gg deps add axon/your-service server.
What it costs
About $42.38 a month on Gagarin: a size-m container at $30.66, a size-s Postgres at $10.22 and 10 GB of disk at $1.50. Traffic is free. Rates: https://gagarin.cloud/pricing
What can go wrong
- The server restarts with
OOMKilled: it is running at size s. Deploy it again with--size m. - A service's calls to axon hang: it has not declared the edge. Run
gg deps addfor it; Gagarin's network denies by default. - Never run
gg domain addonserver: anyone could read every memory. Put the gateway from DEPLOY.md in front of it instead. - Do not change
ENCRYPTION_KEYwithgg resource rotatealone: the database is bound to the key. DEPLOY.md has the re-encryption steps.
Run it locally
docker compose up -d db
npm install
cp .env.example .env
npm run axon -- serveClean up
gg destroy axonGagarin emails the project owner a button to approve the deletion. The memories go with the database.
The full write-up
The README covers the tools, the REST API and how memories link to each other, and DEPLOY.md the gateway and day-two operations.