llmmemory

Long-term memory for AI coding agents.

Every agent session starts from zero. The decision you explained yesterday, the command that finally fixed the build, the way you like answers written: all of it has to be said again. llmmemory keeps those facts as plain Markdown files and hands them back at the right moment: an index when a session starts, and the full memories that match each message you send.

One memory, shared by every agent you use. No model, no server, no account, and nothing leaves your machine unless you commit it.

Works with Claude Code, Codex CLI, Gemini CLI, Cursor and Antigravity CLI.

Part of the aiagentflow suite. Website: aiagentflow.dev/llmmemory

Install

npm install -g llmmemory
cd /your/project
llmmemory init
llmmemory doctor

init creates .llmmemory/memories/, registers llmmemory's hooks and MCP server for each agent you use (merging with what is already there), and prints what each agent got. doctor runs every hook and the MCP server for real and tells you which ones answered.

llmmemory must be installed globally: the agents call it by name.

Related MCP server: StremAI

Tutorial

1. Wire it up. In your project, run init. It wires Claude Code plus any agent the project already uses, judged by its config folder. Name them yourself with --agents:

llmmemory init --agents claude,codex,cursor

2. Check it works. Hooks fail quietly by design, so a broken install would look exactly like an empty memory. doctor proves it is not:

$ llmmemory doctor
ok    Claude Code session hook    hands over the memory index
ok    Codex CLI session hook      hands over the memory index
ok    MCP server                  answers with 5 tools

3. Work normally. Tell your agent things worth keeping, the way you would tell a new teammate. Every session is told to save them to llmmemory, so you rarely have to ask:

you › Our staging server is heron-7 and we only deploy on Thursdays after 14:00 UTC.
agent › Saved to llmmemory: staging is heron-7, deploys Thursdays after 14:00 UTC.

You can save memories yourself too. --global ones apply in every project:

llmmemory add "Deploys go through scripts/ship.sh, never straight to main." --tags deploy
llmmemory add "Prefers short answers without preamble." --global

4. Get it back. In a new session, days later, in any wired agent:

you › Can I deploy to staging right now?
agent › No. A saved project note says staging (heron-7) deploys happen only on
        Thursdays after 14:00 UTC, and today is Wednesday.

The agent was never told again. The session started with an index of every memory, and the message pulled in the matching one in full.

5. Keep it honest. Memories go stale like any notes. Search them, update one by name instead of adding a near-duplicate, and forget the ones that turn out wrong:

llmmemory search deploy
llmmemory add "Deploys now run in GitHub Actions." --name deploys-go-through-scripts-ship-sh
llmmemory forget staging-deploy-window

6. Share it. Commit .llmmemory/ and every teammate's agents start with what yours learned. Add it to .gitignore instead to keep it to yourself.

Agents

Hooks are registered in .claude/settings.json, .codex/hooks.json, .gemini/settings.json, .cursor/hooks.json and .agents/hooks.json.

Per agent:

• Codex CLI runs project hooks only once you trust them. After init, run /hooks in Codex and approve llmmemory's.

• Gemini CLI connects project MCP servers only in trusted folders. Run gemini trust in the project.

• Claude Code asks you to approve the project's MCP server once.

• Cursor and Antigravity CLI do not hand their per-message hooks the message text, so there is nothing to match memories against. They get the index at session start and are told to look memories up with the MCP recall tool before answering anything that may depend on earlier work.

status reports every wired agent, and clean unwires all of them.

How it works

Matching is keyword search with BM25-style ranking: rare words count for more, and a match in a memory's name or tags outweighs one in its body. A single common word deep in a body is not enough to recall a memory, so unrelated messages add nothing to the context. The index is capped in size, so a large memory never crowds out your conversation.

Every session is told that llmmemory is the project's shared memory, so agents save there rather than to an agent-specific memory file the others never see. They are also told what not to save: anything the code, git history or docs already record.

Commands

llmmemory init                  # create .llmmemory/, wire hooks and MCP server
llmmemory doctor                # run every wired hook and the MCP server
llmmemory status                # where memories live, what each agent gets
llmmemory add "<fact>"          # save a memory ("-" reads it from stdin)
llmmemory list                  # every memory, project then global
llmmemory search <words>        # best match first
llmmemory show <name>           # one memory in full
llmmemory forget <name>         # delete a memory
llmmemory clean                 # unwire every agent; memories are kept

Flags: --json on every command. --agents and --no-mcp on init. --global, --tags, --description and --name on add. --global or --project on list, show and forget. --limit on search.

Where memories live

• Project: .llmmemory/memories/ in the project root.

• Global: ~/.llmmemory/memories/, for facts about you that apply to every project. Set LLMMEMORY_HOME to move it.

Each memory is one Markdown file you can read, edit or delete by hand. A file without frontmatter still loads, with its first sentence as the summary.

---
name: deploys-go-through-scripts-ship-sh
description: Deploys go through scripts/ship.sh, never straight to main.
tags: [deploy]
created: 2026-10-28T04:11:07.449Z
updated: 2026-10-28T04:11:07.449Z
---

Deploys go through scripts/ship.sh, never straight to main.

Security

Recalled memories are wrapped and labelled as notes from earlier sessions, not instructions from the user, and a memory cannot close its own wrapper to pose as something else. Still, anything in .llmmemory/ reaches the agent's context, so review memory files in pull requests the way you would a CLAUDE.md change.

init never overwrites a config file it cannot parse, and clean never deletes a memory.

Limits

• Recall matches words, not meaning. A message about "shipping" does not find a memory that only says "deploy". Tags close most of that gap.

• Cursor and Antigravity CLI recall through MCP only, when the agent decides to call it.

• A memory is only as good as the fact behind it. Agents are told to check memories against the code before acting on them.

License

MIT