Docs

The details behind the overview. To try the page itself, open the live demo.

A memory file

One Markdown file per memory, in memories/YYYY/MM/<id>.md of your data repository; the folders only keep listings short.

---
id: 20261002-shop-web-v3-freeze-5xtp
name: shop-web-v3-freeze
type: project
scope: heredescription: "shop-web v3 feature freeze on 2026-11-01: no schema migrations after that date"created: 2026-10-02T16:45:00+08:00
source:
  tool: claude-code
  session_name: shop-web-v3-plan
  host: laptop
  git_remote: git.example.com/shop-web
  git_branch: main---
Feature freeze for shop-web v3 is 2026-11-01. After that only bug fixes land.

**Why:** the data team snapshots the schema for the Q4 reporting work.

**How to apply:** if a change needs a migration, flag it before the freeze.

Type and scope. user (who you are), feedback (how you want work done), project (facts about a project) or reference (where to find things). global loads everywhere, here only where it was recorded.
Description. One line, under 150 characters: what the session index shows.
Source. Stamped by the Stop hook, never by the agent: tool, session, model, host, folder, repository, branch and commit.
The memory. The fact first, then why, then how to apply it, as PROTOCOL.md asks.

Agents write new memories into a per-session staging folder and edit existing files in place. At the end of each turn the Stop hook stamps ids and provenance, moves staged files into memories/, commits, and pushes in the background when the repository has a remote.

Where memories load

At session start a hook injects an index, under the 10,000-character hook limit: every global memory, plus the here memories recorded close to where the session runs, closest first.

Same folder100

Same git checkout, same host90

Same remote: other clones and worktrees80

The session runs inside its folder70

Its folder is inside the session's60

Your home folder and its direct children, such as ~/repos, are too broad to match by containment. Sessions in throwaway folders (Claude Code scratch workspaces, Codex per-thread folders) file their here memories under the project folder they worked in most, keeping the original as source.original_cwd; mem relocate does the same for existing memories. mem index shows what a session started in the current folder would see.

Install

uv tool install "agent-memory-git[ui]"   # the mem command; [ui] adds numpy for mem ui
mem init ~/repos/agent-memory-data       # the data repository and ~/.config/agent-memory
mem import claude --dry-run              # preview, then run without --dry-run
mem import codex --dry-run
mem install --dry-run                    # every change, as a diff
mem install

Codex asks you to trust new hooks once: open /hooks in Codex and enable the three agent-memory hooks. A remote is optional: give the data repository a private one to share memories across machines, or leave it out and everything is still committed, on this machine only. agent-memory-data-demo shows what one with a remote looks like: the demo memories, committed the way the hooks commit them. mem install edits these files and records each edit in ~/.config/agent-memory/install-state.json:

File	Change
`~/.claude/settings.json`	SessionStart, UserPromptSubmit, Stop and SessionEnd hooks; `autoMemoryEnabled: false`; read and edit permission on the data repository; `mem search/list/show` allowed
`~/.claude/CLAUDE.md`	a marked block importing `~/.config/agent-memory/PROTOCOL.md`, a copy of the protocol
`~/.codex/hooks.json`	the same four hooks
`~/.codex/config.toml`	Codex's own memories off; the data repository added to the writable roots
`~/.codex/AGENTS.md`	a marked block with the protocol
`~/.zshrc` or `~/.bashrc`	a marked block putting `~/.local/bin` on PATH, only if a new login shell lacks it

Upgrading. Use Update in mem ui's Settings, or run uv tool upgrade agent-memory-git and then mem install, which refreshes the protocol copies. mem doctor says when they are out of date.

Uninstalling. mem uninstall reverts exactly those edits, keeping other changes the tools made since, and puts each tool's own memory settings back as they were. The data repository is never touched.

mem ui

mem ui serves the page on 127.0.0.1 while its terminal stays open. Every API request needs the token from the link it prints, new each run, so other web pages cannot read or change memories. Each change is one git commit with Undo; if an agent edits the same file meanwhile, saving is refused rather than overwriting.

Search by meaning and similar memories use Qwen3-Embedding-0.6B (int8 ONNX) on the CPU, in a separate uv run --with onnxruntime --with tokenizers environment. Get the model once with mem ui --fetch-model (about 625 MB; a pinned revision, its weights checked by SHA-256). Without it, or with --keywords-only, similar memories come from keywords and search matches words only. Keywords are the words that most set a memory apart (TF-IDF); words that should never be keywords, such as your own name, go in Settings.

Profiles

A profile is a separate set of memories: its own data repository, with its own remote or none. Keep one area's memories from shaping another's: work and personal, or one client and the next. Both tools load and save memories in the active profile, sessions already running included: after a switch, a running session gets the new profile's index with its next message and saves there from then on. A reply already under way finishes in the profile before, and memories a session has already read stay in its context, so start a new session for a clean slate. When there is more than one profile, the index says which one it is from.

Each profile gets a name of two words, such as Quiet Harbor, picked when it is made, and a picture drawn from that name; neither changes. In mem ui, Settings opens on the active profile, and its picture at the bottom of the rail leads there: switch, add and remove profiles at its foot. Switching there also changes the profile the page shows, and first says what it means for running sessions, until you tick Don't show this again; the live demo has two to try. From a terminal, use mem profile:

mem profile                                   list them; * marks the active one
mem profile add ~/repos/agent-memory-work [--remote URL]   prints the name it got
mem profile use quiet-harbor                  sessions use Quiet Harbor from their next message
mem profile remove quiet-harbor               forget it; the folder and remote stay

A new or empty folder becomes a fresh repository, or a clone of the remote when that already has memories; an existing memory repository is used as it is. Folders holding anything else are refused. Adding or removing a profile also updates the folders Claude Code and Codex may read and write, without touching the hooks.

Commands

mem init DIR                    create the data repository and the config
mem install [--dry-run]         wire the hooks and the protocol into both tools
mem uninstall [--dry-run]       put those files back as they were
mem import claude|codex         bring in each tool's existing memories
mem index [--cwd DIR]           what a session started here would see
mem list [--global|--here] [--all] [--type T]
mem search WORDS... [--all]     full-text search; --all includes other places
mem show ID|NAME|PATH
mem add --name N --type T --scope S --description D BODY|-
mem flush                       commit anything left in staging
mem relocate [PATH...]          re-file memories recorded in throwaway folders
mem sync [--pull-only]          pull --rebase and push the data repository
mem lint [ID...] [--summary]    memories that do not follow the format
mem ui [--port N] [--no-open]   the page; --demo opens made-up memories instead
mem profile [use|add|remove]    separate memory repositories to switch between
mem doctor                      check the installation

Every command has --help.

Configuration

~/.config/agent-memory/config.json, written by mem init and by Settings in mem ui:

Key	Effect
`data_dir`	the data repository (the active profile's, when there are profiles)
`profiles`, `profile`	each profile's name and folder, and which one is active; written by `mem profile` and Settings
`keyword_stopwords`	words never used as keywords
`check_updates`	`false` turns off the daily check for a new release
`switch_note`	`false` stops saying what a profile switch means for running sessions; Don't show this again sets it
`throwaway_patterns`	folders treated as throwaway, in place of the built-in ones
`embed_model_dir`	where the embedding model is, instead of `~/.cache/agent-memory/models`

AGENT_MEMORY_DATA points any command at another data repository for one run, and AGENT_MEMORY_CONFIG_DIR at another config folder.

Development

uv sync --all-extras            # dev tools and numpy
uv run pytest
uv run ruff check . && uv run ruff format .
uv run scripts/site.py serve    # this site and its live demo, at http://127.0.0.1:8800/

The page mem ui serves is plain HTML, CSS and JavaScript modules in src/agent_memory/webui/, with no build step and no npm packages: edit a file and reload. uv run mem ... runs the working copy without touching the installed one; to have every session use it, install it in place of the release:

uv tool install --force --editable ".[ui]" && mem install     # the checkout, live
uv tool install --force "agent-memory-git[ui]" && mem install   # the release again

To release, uv run scripts/release.py prepare patch opens a version PR; once it is merged, uv run scripts/release.py publish <PR_NUMBER> creates the GitHub Release and GitHub Actions publishes it to PyPI.

Hooks never fail the host session; their errors go to <data>/.cache/agent-memory.log, and mem doctor reports recent ones. Git operations take turns through a lock file, so parallel sessions on one machine are safe; across machines, unique file names keep merge conflicts rare, and a failed rebase is aborted and logged for you to resolve.