An Airy Spirit

Your agent's own memory. Experience that outlives the session.

Every session, an AI agent starts from zero. The corrections it earned yesterday, the mistakes it already made, what it learned about how you work — gone with the context window. An Airy Spirit gives the agent a memory of its own, on your machine, so that experience accumulates instead of evaporating.

Not a store of documents about your project — your repository already holds those. A record of how the agent itself works: where it tends to be wrong, which corrections it was given and why, what it decided and what came of it.

The memory is a graph that lives the way memory does. New material settles into connections during sleep; connections fade with age, yet nothing is deleted, and a memory rises again when it is needed, because an approach that was wrong a month ago may be right under today's conditions. Over time the agent comes to hold positions rather than a readiness to agree. Our aim — a goal, not a claim — is that experience, kept long enough, becomes a self.

One program, written in Rust from the storage engine up. No cloud, no LLM, no interpreter.

Why not files

Your agent already reads files at startup — CLAUDE.md, AGENTS.md, a folder of analysis. They answer how this code is built. Memory answers how the agent is built.

• Calibration, not knowledge. "I conclude something is absent after failing to find it on the first pass" is not a fact about any file. It is a fact about the agent, and it fires every time.

• A correction is earned, not spent. The agent decides what is worth keeping and writes it down; remembered once, it is there in every session after. Nothing is harvested from the conversation wholesale.

• Experience crosses projects. Patterns of behaviour are recognised wherever they recur — in another repository, another language, another goal. A file stays in the repository it was written in.

• It moves as one piece. Copy it, encrypt it, carry it to a server or a container: on the new machine it is the same memory, not a hundred scattered files that are "roughly the same, I think".

• Forgetting is designed in. What is used rises, what is not dims, and a place in long-term memory is earned. The agent's own replies leave short-lived episodic traces; sleep keeps the few that prove valuable and lets the rest go. What the agent chose to write itself stays.

The whole argument, written for the agent itself, is in onboarding/ — in English, Spanish, French, Brazilian Portuguese, Russian, Simplified Chinese and Traditional Chinese.

Related MCP server: ClawMem MCP Server

What it gives the agent

Recall by connection, not by keyword. Every memory is a node, and edges carry meaning: similarity, contradiction, supersession, part of a whole. A query starts from the direct matches and spreads along the edges to their neighbours, so "what did we decide about X" is found through what it is connected to.

Consolidation while idle. A light sleep runs on its own as material arrives. A deep sleep — the one that groups memories into topics and finds how they relate — runs by itself when it is due and the machine is idle, once automatic deep sleep is on (one click in the menu bar); until then the agent is told when it is due. A deep sleep is all or nothing: if it fails halfway, the memory is exactly as it was before it began.

Two dates on every memory. When the thing happened, and when the agent wrote it down. So "last week" finds what happened last week, even if it was recorded today.

People and things. Names of people, projects and places are picked out automatically, and a name spelled two ways stays one person instead of becoming two.

Search that explains itself. Any search can show its work: what each step found, how long it took, and why the results came out in that order.

Your data

• On your disk. Everything lives in one folder. A crash or a power cut loses nothing that was already written.

• No cloud, no LLM. Models download once at setup (about 1.5 GB; an offline install is supported). If that download breaks off, the service finishes the entity model in the background; after that nothing leaves the machine. No telemetry. The one exception is yours to make: an optional writeback mode (llm, off by default) calls a model at the address you give it.

• Encrypted if you want it. Three modes: none; passphrase asked at every start and held in memory only; passphrase on disk for unattended boot. Switch between them at any time; the data stays.

• Recoverable by you alone. Every install gets its own 24-word recovery phrase, generated locally. It lifts an emergency stop and resets a forgotten passphrase.

• Stoppable. An emergency stop in three strengths; the strongest survives a restart, and only the recovery phrase lifts it.

• Portable. One encrypted file carries the whole memory to another machine.

Works with

Agents: Claude Code, Claude Desktop, Gemini CLI, Antigravity, Codex, Cursor, Grok, Kiro — connected over MCP; where the agent supports it, memory is also brought into the conversation at the start of a session. Any other MCP client works with a manual config.

Platforms: macOS 11+ (Apple Silicon and Intel, one universal app); Linux x86_64 and arm64 (.deb, .rpm, .tar.gz; glibc 2.34+); Docker (amd64, arm64).

Machine: about 2 GB of RAM while running and 1.5 GB of disk for the models. On a machine with 16 GB or more, search orders its results with a larger, more accurate model.

Languages

Install

macOS — open the disk image and the app; it walks you through setup.

Windows — there is no Windows build: run it in Docker Desktop (below), or inside WSL with the npm or Linux steps.

Homebrew (macOS, Linux):

brew tap seventhwalllab/anairyspirit https://github.com/Seventhwalllab/anairyspirit
brew trust seventhwalllab/anairyspirit
brew install anairyspirit
anairyspirit setup

Homebrew installs a ready-made build, so neither Xcode nor Command Line Tools are needed. brew tap clones with git, which has to be 2.24 or newer — an older one fails with unknown option 'end-of-options'; which -a git shows which git comes first in your PATH.

npm (macOS, Linux; Node 18 or newer, and curl, which setup uses to download the models):

npx anairyspirit setup

The package downloads this release's archive for your machine, checks it against the signed checksums and runs setup from it. setup asks you to accept the licence — answer y — and shows a 24-word recovery phrase: write it down. Once installed, an AI client can start the program with npx -y anairyspirit mcp; npx anairyspirit@latest update updates it. (npm i anairyspirit only adds the launcher, as anairyspirit-npm; the install is npx anairyspirit setup.)

The packages and the archive for Linux are on the latest release page; download the one for your system and architecture, then:

Debian, Ubuntu:

sudo apt install ./anairyspirit-cli_<version>-1_<arch>.deb
anairyspirit setup

Fedora, RHEL:

sudo dnf install ./anairyspirit-cli-<version>-1.<arch>.rpm
anairyspirit setup

openSUSE — zypper checks the package signature, so the key comes first:

sudo rpm --import https://raw.githubusercontent.com/Seventhwalllab/anairyspirit/main/KEYS
sudo zypper install ./anairyspirit-cli-<version>-1.<arch>.rpm
anairyspirit setup

Any other Linux — unpack the .tar.gz, then:

cd anairyspirit-<version>-<arch>
./anairyspirit setup

Then open a new terminal, so the shell finds anairyspirit.

Docker — from GitHub's registry (the same image is on Docker Hub as seventhwalllab/anairyspirit). It needs about 5 GB of memory; the first start downloads the models (about 1.5 GB) and takes a few minutes. Starting it accepts the licence (docker exec anairyspirit anairyspirit license shows it).

docker run -d --name anairyspirit -v anairyspirit-data:/data \
  -v anairyspirit-models:/home/anairyspirit/.cache/anairyspirit \
  --restart unless-stopped ghcr.io/seventhwalllab/anairyspirit:latest

Then connect your AI client. It stays on the computer that runs Docker and runs this command, which reaches the memory inside the container — no port, certificate or token:

{ "command": "docker", "args": ["exec", "-i", "anairyspirit", "anairyspirit", "mcp"] }

Claude Code: claude mcp add --scope user anairyspirit -- docker exec -i anairyspirit anairyspirit mcp.

The client gets the memory owner's rights. Optional: to give it less, issue a read-only token — docker exec anairyspirit anairyspirit token issue --raw --scope read --name my-agent — and pass it through the client's environment, not its arguments: "args": ["exec", "-i", "-e", "ANAIRYSPIRIT_BEARER", "anairyspirit", "anairyspirit", "mcp"] with "env": {"ANAIRYSPIRIT_BEARER": "<token>"}. The recovery phrase: docker exec -it anairyspirit anairyspirit recovery. A client on another machine connects over the network: docker exec anairyspirit anairyspirit man install-docker, «Reaching it from outside the container».

To update, keep a copy first — docker exec -it anairyspirit anairyspirit export-full --out /data/backup.mehsnap — then docker pull the newer image, docker stop anairyspirit && docker rm anairyspirit, and the same docker run again, with every flag you added at the first run. The memory and the models are on the two volumes and stay. Details: docker exec anairyspirit anairyspirit man install-docker, «Updating».

The image is signed: cosign verify --key anairyspirit-release.pub ghcr.io/seventhwalllab/anairyspirit:latest with cosign 3 and the key from the release page (cosign 2 answers «no signatures found»).

Every release carries a checksum manifest, SHA256SUMS, signed with GPG in SHA256SUMS.asc (key in KEYS): gpg --verify SHA256SUMS.asc SHA256SUMS, then sha256sum --check --ignore-missing SHA256SUMS. The manual ships with each release in docs/ and inside the program: anairyspirit man.

Benchmarks

LongMemEval — finding the right past conversation. For each of 470 questions the memory is given that question's chat history, about 48 sessions, and searched once; the score is whether the session holding the answer comes back in the top five.

Hit@5: a session with the answer is in the top five. Recall@5: the share of all answer sessions found there — some questions need several. Retrieval only: no language model answers and none judges, so this is the benchmark's session-level memory recall, not end-to-end QA accuracy. No large language model takes part in storing, searching or ranking: they run on small local models — an embedding model and a cross-encoder reranker — plus BM25. With the default settings there are no LLM calls, no API, and nothing leaves the machine apart from the model download at setup (if that breaks off, the service finishes the entity model in the background); the one other exception is an optional writeback mode that you switch on and point at a model yourself. LongMemEval-S, questions without an answer excluded; public build 0.1.392 with its default settings.

Benchmark: Wu et al., LongMemEval: Benchmarking Chat Assistants on Long-Term Interactive Memory — arXiv:2410.10813.

FinOps

What the service takes, for a memory of about 12 thousand records. We strongly recommend at least 5 GB of memory. Figures are High / Balanced — the two search qualities in the menu-bar app.

The full figures, disk use and which quality to choose: docs/FINOPS.md.

Under the hood

Written in Rust, from the storage engine up — about 290,000 lines: the graph store, vector index, search pipeline, encryption, the service, the command line, the menu bar and the setup windows. No Python, no JVM, no interpreter at runtime. The one exception is a 380-line Node bridge that Claude Desktop's extension format requires; the program writes it out when you connect that client.

Every mechanism above is named with the published work it comes from, where there is one. Several are borrowed from memory science rather than from search engineering — that is deliberate, and it is the part of the design worth arguing about.

What this is built on — the papers behind each mechanism, with authors and links, and a plain statement of which parts are ours.

Licence

LICENSE and EULA; translations in legal/.

Seventh Wall Lab · Chile · seventhwalllab.com