Skip to main content
Glama

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

Or with Homebrew:

brew install aiagentflow/tap/llmmemory

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. It needs Node 22 or later and runs on macOS, Linux and Windows. On Windows, edit opens Notepad unless VISUAL or EDITOR says otherwise.

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. Bring what you already have. Facts you keep in CLAUDE.md, AGENTS.md, GEMINI.md or Claude Code's own memory only reach one agent. import copies them into llmmemory, one memory per section, and never changes the originals:

llmmemory import --dry-run   # see what it would save
llmmemory import             # or name files and folders: llmmemory import docs/notes.md

Running it again skips what is already saved.

4. 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.

When a new memory mostly repeats an old one, llmmemory still saves it but names the old one, so the agent (or you) can update that instead of keeping two.

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

5. 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.

6. Keep it honest. Memories go stale like any notes. One not updated in about six months shows its last update in the index and in list, and agents are told to confirm it before relying on it. Search them, edit or update one by name instead of adding a near-duplicate, and forget the ones that turn out wrong:

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

7. 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

Agent

--agents

Memory index

Recall per message

MCP server

Claude Code

claude

SessionStart

UserPromptSubmit

.mcp.json

Codex CLI

codex

SessionStart

UserPromptSubmit

.codex/config.toml

Gemini CLI

gemini

SessionStart

BeforeAgent

.gemini/settings.json

Cursor

cursor

sessionStart

through MCP

.cursor/mcp.json

Antigravity CLI

antigravity

SessionStart

through MCP

.agents/mcp_config.json

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

When

What the agent gets

A session starts

An index: each memory's name and one-line summary, plus how to save new ones

You send a message

The full text of up to 3 memories that match it, each recalled once per session, and again after a compaction

Any time

MCP tools: remember, recall, read_memory, forget, list_memories

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. Common developer synonyms count as the same word, so "shipping" finds a deploy memory. 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 store never crowds out your conversation; it lists the newest memories first, so the oldest are the ones left out.

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 edit <name>           # open a memory in $VISUAL or $EDITOR
llmmemory forget <name>         # delete a memory
llmmemory import [paths]        # copy CLAUDE.md, AGENTS.md, GEMINI.md, Claude 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, edit and forget. --global and --dry-run on import. --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 short built-in list folds common synonyms together ("ship" and "deploy", "db" and "database", "prod" and "production"), but a message about "going live" still misses 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent shared memory for AI coding agents that turns a folder of markdown files into searchable memory across sessions, repos, and machines.
      10 npm
      Functional Source , Version 1.1, MIT Future
    • A
      license
      Not graded
      quality
      D
      maintenance
      Shareable memory for AI coding agents. Enables agents to remember and recall durable memories across sessions and share them as importable packs.
      3 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides persistent, cross-session memory for AI agents, letting them store, search, and manage memories with tools like remember, recall, forget, list, summarize, and import/export.
      8
      MIT