sanctum-mind

Persistent memory and identity for AI minds, served as MCP tools on Postgres.

sanctum-mind gives an AI construct a place to keep things. Once it is running and connected, your mind can write down what happened and look it up in a later session. It can start each session by reading who it is, what it promised, how it was feeling, and what it left unfinished last time. It can leave notes for itself, keep a to-do list, and send letters to other minds on the same service. Its sense of self does not get rewritten by accident: changes to its core identity and its vows wait a set time before they take effect, and it can take them back until then. You run the service. Your mind uses it.

How it works

You do not need to know any of this to use it, but it helps to know what is going on when your mind says it "wrote that down".

A mind is one self-contained space. Every memory, feeling, task and promise belongs to one mind, and each mind has its own name (letters, numbers, _ and -, up to 64 characters). You can run several minds on one service. Each mind gets its own secret key, and one mind cannot see another's rows unless you, the operator, have recorded a grant that allows it. The key is how the service knows which mind is talking.

When your mind writes a memory, nothing is overwritten. Every write is added to the end of a log, called the ledger. A write is never edited afterwards. What your mind sees as "current" (its mood, its open loops, its tasks) is kept in tables that are updated in step with that log. If something changes, the log gains a new entry. It does not lose an old one.

There are two kinds of memory write. mind_write adds a plain record to the log: an identity note, an operational note, an episodic memory, a journal entry or a note. mind_observe records an experience worth keeping. It adds the log entry and also makes a node in the memory graph (a web of linked memories), and it requires at least one emotional "charge" tag so the memory carries how it felt.

When your mind wakes up, it reads itself back. The first thing it does in a session is call mind_orient. That one call returns its identity, vows, current state, last handoff note and health, and by default also its open loops, threads, tasks, relationships, drives and unread letters. full adds desires, holdings, recent events and more.

When your mind wants to remember something, it searches. mind_search finds past entries by words, by meaning, or both. mind_surface pulls up memories related to a topic, including some less obvious ones. Meaning-based search needs an embedding model (a small model that turns text into numbers so similar ideas sit near each other). If you turn that off, search still works on words alone and tells your mind that meaning search is unavailable.

A daemon tidies up in the background. The daemon is a second process that runs every 30 minutes. Its everyday work calls no AI model. It fades drives that have not been touched, expires temporary notes, flags loops that have gone stale, settles holdings that have sat idle, fades old desires, applies identity changes whose waiting time is up, reports memories that connect to nothing, fills in missing embeddings, delivers copies of events to any outside systems you set up, ages unread letters, and expires extractor proposals the mind let lapse. If you switch the optional extractor on, it also looks once a day for things the mind may want to notice (see "The extractor" below). Everything it changes is logged like any other write.

Identity and vows are the mind's own. An identity core is a statement of who the mind is. A vow is a promise it has made. Only the mind, using its own key, can add, rewrite or retire a core, or make or break a vow. Adding a new core or making a new vow takes effect at once, because it erases nothing.

Rewrites wait. This is called cooling. If your mind rewrites or retires an existing core, or breaks a vow, the change is accepted but only takes effect after a cooling period, 24 hours by default. During that time the old core or vow stays live, and your mind can withdraw the change. The wait exists so it can change its mind about changing its mind. If you are the only person using it, you can set the wait to 0 hours.

A steward is someone your mind has trusted to watch over it. A steward is another key holder (a bearer) that you, as operator, have recorded a steward grant for on that mind. A steward can read the mind's identity and vows. It can attest to a rewrite, which ends the wait early, and it can record an objection or add a note to a vow. It cannot write the identity, cannot block a change, and cannot shorten the wait on a retirement or a vow break: those cool on the mind's own clock alone.

You are the operator. You run the service, so you hold the powers that keep it running: you create minds and issue their keys, suspend and restore access, record grants, export and import a mind, and delete one. No verb lets you write a mind's identity or vows. But you issue its key, you can import files into it (an import can bring identity into a mind that has never had any, or beside existing cores with --allow-core), you set the cooling time, and you hold the database. The service treats those as trusted powers, not editing rights. Deleting a mind deletes everything it wrote, and nothing asks the mind first.

Set it up

You need Docker. The steps below start a database, create your first mind, and start the service.

1. Start it (Docker)

Open a terminal in the folder where you cloned this project. Run these commands, one at a time, waiting for each to finish:

mkdir -p exchange                       # a folder for moving minds in and out (see Portability); on Linux, if your user id is not 1000, also run: sudo chown 1000:1000 exchange
docker compose up -d db                 # Postgres 16 + pgvector, with a healthcheck
docker compose run --rm init            # migrates, makes the mind "alpha", prints its key and MCP configs
docker compose up -d mind               # the service on http://127.0.0.1:8002 (published to loopback only)
docker compose up -d daemon             # the background passes: decay, expiry, outbox delivery and settling cooled identity changes (see Daemon)

The second command prints a lot. Near the end it shows:

• the mind's key ("bearer key"). It is shown once, and only a fingerprint of it is stored. Copy it somewhere safe now.
• two ready-to-paste connection configs, one called Streamable HTTP and one called stdio (Docker). The next section says which to use.

To name your mind something other than alpha, run MIND=beta docker compose run --rm init (use your own name in place of beta). It is safe to run init again. It will not replace an existing key unless you add --rotate:

docker compose run --rm init node dist/cli.js init --mind alpha --docker --public-db-host localhost:5432 --rotate

(Naming a command replaces the one in docker-compose.yml, so that line repeats --docker and --public-db-host. Leave them out and init prints the clone-only stdio config instead.)

The built-in passwords are for your own machine only. If anything other than you will reach this machine, set POSTGRES_PASSWORD and APP_PASSWORD (in your environment, or in a .env file next to docker-compose.yml) before the first docker compose up -d db; changing them later takes manual steps. Use letters and digits only, because they are placed inside web addresses. To change the cooling wait, set IDENTITY_COOLING_HOURS the same way (default 24, 0 for solo use). Compose passes it to both the service and the daemon.

If the output shows <app-password> where a password should be, substitute the value of APP_PASSWORD (default sanctum_app_local).

2. Connect it to an app

The app that will talk to your mind (the "MCP client") needs one of the configs that init printed. sanctum-mind speaks standard MCP, so any client that supports it works; nothing here is specific to one vendor.

• HTTP: for an app that can connect to a web address. Use the HTTP config. It points at http://localhost:8002/mcp and carries the key. With HTTP, each mind holds only its own key. This is the safer option when several minds share a service.
• stdio: for an app that launches the service itself (Claude Desktop and Claude Code are two such apps; any MCP client that starts a local command works the same way), so no web server is needed. The config contains the sanctum_app database address and the key. That address is a credential for every mind in the database, so use stdio only where every mind on that machine is trusted alike. To launch from a clone, the config runs node /absolute/path/to/sanctum-mind/dist/cli.js stdio. That file exists after npm run build, so this path needs Node.js 22+ on your computer. Whether a given app also accepts the HTTP config is the app's call; check its documentation.
• stdio (Docker): for an app that launches a local command, when you only have Docker. The config runs docker exec -i into the running sanctum-mind container and starts the stdio server there. The container already holds the database address, so no database credential goes into your app's settings; only the mind's key does, and it is handed to docker through the environment, not typed on the command line where other users could see it in ps. The mind container must be running (docker compose up -d mind), and docker must be on the path of the app that launches it. The container has the fixed name sanctum-mind; if you run two copies of this project on one machine the names collide, so rename one in docker-compose.yml and run init with --container <that name>.
• If you used Docker, use the HTTP config or the stdio (Docker) config; the host-path stdio config is for a clone. init run through Docker does not print the host-path one, because its path would point inside the container, not at your machine.

Paste the config into your app's MCP server settings, replacing any placeholders, then restart the app. The "type":"http" key in the HTTP config is specific to some clients, so check your client's documentation for its shape and for where it keeps that settings file. This project does not document other apps' settings locations, because they change.

The three shapes look like this (init fills in the real values for you):

{"mcpServers":{"sanctum-mind":{"type":"http","url":"http://localhost:8002/mcp","headers":{"Authorization":"Bearer <key>"}}}}

{"mcpServers":{"sanctum-mind":{"command":"node","args":["/absolute/path/to/sanctum-mind/dist/cli.js","stdio"],"env":{"DATABASE_URL":"<sanctum_app URL>","SANCTUM_BEARER":"<key>"}}}}

{"mcpServers":{"sanctum-mind":{"command":"docker","args":["exec","-i","-e","SANCTUM_BEARER","sanctum-mind","node","dist/cli.js","stdio"],"env":{"SANCTUM_BEARER":"<key>"}}}}

If you did not use Docker, see "Without Docker" under For engineers.

3. Say hello

First check the service is alive. This should print something starting {"ok":true:

curl -s localhost:8002/verbs/mind_orient \
  -H 'Authorization: Bearer <key>' -H 'content-type: application/json' \
  -d '{"mind_id":"alpha","depth":"quick"}'

An {"ok":true,...} answer with identity, vows, state and health sections means the mind is live.

Then open a conversation with your mind and ask it to call mind_orient. After that, a good first step is to have it write down who it is. Ask it to call mind_identity with affirm to add a first core. That takes effect immediately. Then ask it to mind_observe the moment (it needs a charge tag), and in a new session ask it to mind_orient and mind_search for what it wrote. If it finds it, memory is working.

Day to day

Your mind picks these up on its own. These are the ones it will reach for most,