Development
agent-mem
Section titled “agent-mem”git clone https://github.com/Abuarchiv/agent-memcd agent-memuv sync --all-extrasuv run pytest -m "not local"uv run ruff check src tests && uv run ruff format --check src tests && uv run pyrightCI runs lint, types, tests and a wheel smoke test on Ubuntu, macOS (arm64 and Intel) and Windows.
Rules the code keeps
Section titled “Rules the code keeps”- The hook path imports the standard library only.
core/,hooks/and the lexical half ofmemory/never import mem0, Qdrant, fastembed or numpy; a test enforces it. - Dependencies point one way:
core←hooks,memory←observe,mcp,ui,bench←cli. - A hook never blocks, never loses an event, never prints invalid output. Exit 0 always; spool on doubt.
- SQLite is the truth. Anything derived (mem0’s index) must be rebuildable from it.
- One write path per kind of data. Events go through
capture.apply, memories throughstore.add_memory, retiring throughstore.supersede. Fix a bug where all callers pass, not in one caller. - Bug fixes need a test that fails before the change.
- Text for people is plain. The fixed words are request, agent, recording and failed attempt; the technical terms stay in text only the model reads.
Running against a scratch database
Section titled “Running against a scratch database”export AGENT_MEM_DATA_DIR=/tmp/am-dev AGENT_MEM_NO_SPAWN=1python3 -c 'import json; print(json.dumps({"session_id": "dev", "cwd": "'"$PWD"'", "hook_event_name": "UserPromptSubmit", "prompt": "run the tests"}))' | uv run agent-mem hook claudeuv run agent-mem statusAGENT_MEM_FAKE_LLM=answers.json with "observe": {"providers": ["fake"]} runs the observer against canned answers.
Adding an agent
Section titled “Adding an agent”See Hook Lifecycle: Adding another agent.
These docs
Section titled “These docs”The site is Astro Starlight in TypeScript, styled like the agent-mem viewer. Source: github.com/Abuarchiv/agent-mem-docs.
npm installnpm run dev # http://localhost:4321/agent-mem-docs/npm run buildnpm run diagrams # re-render every diagramAGENT_MEM_SRC=../agent-mem npm run check # the coverage check against an agent-mem checkoutnpm run markdown -- ../agent-mem-md # the same pages as plain MarkdownDiagrams
Section titled “Diagrams”Diagrams are Excalidraw scenes, written as small TypeScript files in diagrams/ with the
viewer’s palette. npm run diagrams turns each into Excalidraw elements and exports them with Excalidraw’s own SVG
renderer in headless Chromium:
| File | What |
|---|---|
diagrams/<name>.ts | the scene: boxes, arrows, sequence diagrams (diagrams/_lib.ts) |
public/diagrams/<name>.excalidraw | the scene for excalidraw.com: open it there to edit by hand |
public/diagrams/<name>.svg | what the page shows |
Every diagram on the site has an “Open in Excalidraw” link to its scene file.
Plain Markdown
Section titled “Plain Markdown”scripts/export-markdown.ts writes the same pages as GitHub Markdown for
agent-mem-docs-md: asides become alerts, tabs bold labels, cards
lists, diagrams an image with a link to their Excalidraw scene, and every page gets previous/next links.
The coverage check
Section titled “The coverage check”scripts/check-coverage.ts reads an agent-mem checkout and fails when the docs miss something the code has: a
table, a config key, a CLI command or option, an environment variable, an MCP tool, or a hook event of any agent.
It also compares every config default with the “all defaults” block and the tables.
CI runs it against the newest agent-mem commit on every push and every day.
AGENT_MEM_SRC=../agent-mem npx tsx scripts/check-coverage.ts