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

Source: https://github.com/gagarin-cloud/axon
Deploy: https://my.gagarin.cloud/deploy/7h9xs7d3
Costs about $42.38 a month. Checked 2026-11-09.

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

- `server` (service, :7717 · size m, private) → `database`, `axon`
- `database` (Postgres, pgvector 10 GB)
- `axon` (external, ENCRYPTION_KEY)

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](https://github.com/gagarin-cloud/axon/blob/main/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 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](https://github.com/gagarin-cloud/axon/blob/main/README.md) covers
the tools, the REST API and how memories link to each other, and
[DEPLOY.md](https://github.com/gagarin-cloud/axon/blob/main/DEPLOY.md) the
gateway and day-two operations.
