recipe

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.

$42.38 a monthchecked 9 November 2026the codeas markdown

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

NameKindSizeHolds
databasepostgress, 10 GB diskthe memories, with pgvector
axonexternalnoneENCRYPTION_KEY and MAX_MEMORIES
serverservicemaxon 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 axon

The 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 add for it; Gagarin's network denies by default.
  • Never run gg domain add on server: anyone could read every memory. Put the gateway from DEPLOY.md in front of it instead.
  • Do not change ENCRYPTION_KEY with gg resource rotate alone: 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 -- serve

Clean up

gg destroy axon

Gagarin 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.