lillycham/akyuu

Akyuu is a persistent memory store for AI agents, modelled on Nix. A memory is
an immutable plain-text file, named by the hash of its text. A small mutable
layer of named refs says which memory is current, and a graph of links
between memories is derived from the files. An agent reads and writes it
through a command line or an MCP server, so Claude Code, Codex and
other MCP clients can share one memory.
**Status: 0.2.0.0, pre-1.0.** I daily drive Akyuu with all my agents, and
have found it to work well for holding general information and task-specific
information. I test a lot and run the latest main build in my config, so I find
issues quite quickly. With that said, Akyuu should be treated as beta software,
and features and interfaces are likely to change.
Features
- **Remembering facts** - A ref like me/projects/garden names the latest memory. When it needs to be updated, an agent "supersedes" it, and the old one will eventually be *garbage-collected*. History is retained until this happens.
- **Noting down events** - A log (append, note) keeps episodic memory in order.
- **Recall** - Fuzzy search allows some leeway in searching for memories, and you can optionally use an embedding model to get semantic searching.
- **Self-tidying** - check finds forks, stale links, duplicates, and an agent can use that to clean up and consolidate memories.
A web UI (shown above, akyuu serve) is included. This allows the memory bank
to be explored through a wiki interface, as well as visualising the graph,
providing search, and displaying information about the health and function of
the akyuu store.
Quick start & installation
To let an agent do the install, point it at
docs/agent-install.md from a release tag. It asks you
before it changes your files.
The intended way to install Akyuu is through Nix with home-manager.
The home-manager module configures the root, GC, backups and versioning, and
sets up launchd or systemd services to run the above automatically.
It installs the binary, writes the settings to ~/.config/akyuu/config.toml
(akyuu config shows them), and makes the store directory.
See docs/install.md for both, the daily jobs, akyuu-backup
and akyuu-version.
Trust and safety
- **One user.** We do not currently implement access controls. Any agent
connected to the MCP can write to and read from the store. Only give Akyuu
to agents you trust to see your memories.
- **Local.** The MCP server speaks on stdio, and the webview only listens on
localhost.
- **Commands from settings.** The command of an embedding profile is run with
sh -c. It comes from ~/.config/akyuu/config.toml or the environment:
protect that file like a script.
- **Forgetting.** Memories that have been superseded will be garbage collected,
and eventually deleted completely. You can make backups, and akyuu-version
serves to bring memories into Git for versioning and sync.
- **Secrets.** Do not store passwords or keys in memories, as they are