Anairyspirit README

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; what goes unused dims — it is never deleted, and it 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 and Traditional Chinese.

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). After that nothing leaves the machine. No telemetry.
• 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.

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):

npx anairyspirit setup

The package downloads this release's archive for your machine, checks it against the signed checksums and runs setup from it. Once installed, an AI client can start the program with npx -y anairyspirit mcp; npx anairyspirit@latest update updates it.

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):

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

The image is signed: cosign verify --key anairyspirit-release.pub ghcr.io/seventhwalllab/anairyspirit:latest with the key from the release page. The first start downloads the models and takes a few minutes.

Every release carries a GPG-signed checksum manifest (SHA256SUMS-public.asc, key in KEYS). 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 anywhere in the product: storing, searching and ranking run on small local models — an embedding model and a cross-encoder reranker — plus BM25. No LLM calls, no API, nothing leaves the machine. 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