agent-memory

Local-first memory for AI agents.

agent-memory gives Hermes, Codex-style CLIs, Claude-style CLIs, and custom agent harnesses a shared SQLite memory runtime with curation, provenance, retrieval, prompt rendering, and regression evaluation.

It is intentionally small and local-first: your memory database lives on your machine unless you choose to sync or copy it elsewhere.

Why use it?

Most agent memory systems end up as raw logs, ad-hoc notes, or one-shot RAG. agent-memory separates durable knowledge into semantic facts, procedures, episodes, source records, scopes, and lifecycle states so an agent can remember useful context without blindly stuffing every transcript into future prompts.

Use it when you want:

• one user-level memory store shared across multiple agent harnesses
• local SQLite storage instead of a hosted memory service
• approved-only prompt context by default
• candidate/disputed/deprecated memory review flows
• source/provenance metadata for every curated memory
• bounded prompt rendering for Hermes/Codex/Claude wrappers
• retrieval regression fixtures with lexical/source baselines and failure triage

30-second install

Recommended path for CLI agent users:

npm install -g @cafitac/agent-memory
agent-memory bootstrap
agent-memory doctor

What this does:

• installs the agent-memory command
• initializes ~/.agent-memory/memory.db when missing
• creates or merges the Hermes hook config at ~/.hermes/config.yaml
• preserves existing Hermes hooks and appends the agent-memory pre-LLM hook
• lets you verify setup with agent-memory doctor

Python-first alternatives:

pipx install cafitac-agent-memory
agent-memory bootstrap
agent-memory doctor

uv tool install cafitac-agent-memory
agent-memory bootstrap
agent-memory doctor

First memory in 60 seconds

DB=~/.agent-memory/memory.db

agent-memory init "$DB"
agent-memory create-fact "$DB" "agent-memory" "primary-install-path" "npm install -g @cafitac/agent-memory" "user:default"
agent-memory approve-fact "$DB" 1
agent-memory retrieve "$DB" "How should I install agent-memory?" --preferred-scope user:default

Normal retrieval is approved-only by default. Candidate, disputed, and deprecated memories stay out of prompt context unless you intentionally ask for a forensic view:

agent-memory retrieve "$DB" "What obsolete install notes exist?" --status all

Hermes quickstart

For most Hermes users:

npm install -g @cafitac/agent-memory
agent-memory bootstrap
agent-memory doctor
hermes hooks doctor

On first real Hermes use, Hermes may ask you to approve the shell hook or require --accept-hooks depending on your local Hermes policy.

The installed hook calls:

agent-memory hermes-pre-llm-hook ~/.agent-memory/memory.db --top-k 3 --max-prompt-lines 8 --max-prompt-chars 1200 --max-prompt-tokens 300 --max-alternatives 2

The hook receives the Hermes event JSON on stdin, retrieves relevant approved memories, and returns bounded ephemeral context for the current prompt. It does not write back to Hermes session storage.

If you only want to inspect the YAML snippet and not modify config:

agent-memory hermes-hook-config-snippet ~/.agent-memory/memory.db

If you want explicit paths and budgets:

agent-memory hermes-install-hook ~/.agent-memory/memory.db --config-path ~/.hermes/config.yaml --top-k 3 --max-prompt-lines 8 --max-prompt-chars 1200 --max-prompt-tokens 300 --max-alternatives 2 --timeout 12

Codex and Claude prompt wrappers

For harnesses that want a plain prompt prefix rather than a Hermes hook response:

agent-memory codex-prompt ~/.agent-memory/memory.db "What should I remember about this project?" --preferred-scope user:default
agent-memory claude-prompt ~/.agent-memory/memory.db "What should I remember about this project?" --preferred-scope user:default

The command prints prompt text only, so wrappers can prepend it to the live user request before invoking Codex, Claude Code, or another CLI.

This repository also includes source-checkout helper scripts for maintainers:

python scripts/run_codex_with_memory.py ~/.agent-memory/memory.db "What should I do next?" --dry-run
python scripts/run_claude_with_memory.py ~/.agent-memory/memory.db "What should I do next?" --dry-run

End users should prefer the installed agent-memory command unless they are developing this repository.

Data and privacy model

• Default database: ~/.agent-memory/memory.db
• Default Hermes config path: ~/.hermes/config.yaml
• Storage: local SQLite
• Network behavior: the core CLI does not upload your memory database to an agent-memory cloud service
• Prompt policy: approved memories are retrieved by default; candidate/disputed/deprecated memories are excluded unless requested
• Scope policy: user:default is the recommended durable cross-project scope; Hermes can also derive privacy-preserving cwd:<hash> scopes without exposing raw local paths in prompt context

See PRIVACY.md and SECURITY.md for the external-user trust model, sensitive-data guidance, and vulnerability reporting instructions.

Uninstall and rollback

Uninstall the CLI:

npm uninstall -g @cafitac/agent-memory
# or
pipx uninstall cafitac-agent-memory
# or
uv tool uninstall cafitac-agent-memory

Remove the Hermes hook by editing ~/.hermes/config.yaml and deleting the agent-memory hermes-pre-llm-hook ... command from hooks.pre_llm_call.

Keep or remove local data explicitly:

# inspect first
ls -lh ~/.agent-memory/memory.db

# destructive: removes the local memory database
rm ~/.agent-memory/memory.db

agent-memory bootstrap backs up changed Hermes config files to *.agent-memory.bak when it modifies an existing config.

Retrieval evaluation and regression gates

agent-memory includes a fixture-based retrieval evaluator so retrieval behavior can be tested like application code:

agent-memory eval retrieval ~/.agent-memory/memory.db tests/fixtures/retrieval_eval
agent-memory eval retrieval ~/.agent-memory/memory.db tests/fixtures/retrieval_eval --baseline-mode lexical
agent-memory eval retrieval ~/.agent-memory/memory.db tests/fixtures/retrieval_eval --baseline-mode lexical --format text
agent-memory eval retrieval ~/.agent-memory/memory.db tests/fixtures/retrieval_eval --fail-on-regression

Supported baseline modes include:

• lexical: preferred-scope lexical comparator
• lexical-global: lexical comparator that ignores preferred scope
• source-lexical: lexical comparator over linked source content within preferred scope
• source-global: source-linked comparator that ignores preferred scope

Reports include per-task retrieved IDs, expected hits, missing IDs, avoid hits, pass/fail state, aggregate summaries, advisories, and failure triage details such as snippets, lifecycle status, scopes, and policy signals. Text reports are meant for maintainers reviewing failed retrieval tasks in a terminal; JSON is the stable machine-readable surface.

Current maturity

agent-memory is alpha software, but the public install path is validated.

What is ready:

• npm and PyPI releases from the same versioned source
• GitHub Release artifacts
• CI and release metadata checks
• published-install smoke checks
• local SQLite storage
• Hermes bootstrap/doctor flow
• Codex/Claude prompt rendering commands
• approved-only retrieval policy by default
• retrieval regression fixtures and diagnostic reports

Known limitations:

• no hosted sync service
• no built-in encryption-at-rest wrapper around the SQLite file
• no automatic secret detection/redaction before users create memories
• no stable 1.0 API guarantee yet
• advanced graph/semantic retrieval behavior is still evolving
• multi-machine sharing is currently a user-managed file/sync concern

Development

git clone https://github.com/cafitac/agent-memory.git
cd agent-memory
uv run pytest tests/ -q
uv run python scripts/check_release_metadata.py
uv run python scripts/smoke_release_readiness.py
uv run pytest tests/test_published_install_smoke.py -q
npm pack --dry-run

After a release publishes, the published-install-smoke workflow verifies the exact npm/PyPI version through npm registry lookup, npx, npm exec, uvx, and pipx. Maintainers can also run it manually with gh workflow run published-install-smoke.yml -f version=<version>.

Useful source-checkout commands:

uv run python -m agent_memory.api.cli --help
uv run python -m agent_memory.api.cli hermes-bootstrap /tmp/agent-memory.db --config-path /tmp/hermes-config.yaml
uv run python -m agent_memory.api.cli hermes-doctor /tmp/agent-memory.db --config-path /tmp/hermes-config.yaml

Repository docs

• docs/install-smoke.md: published install smoke recipes
• SECURITY.md: vulnerability reporting and local security model
• PRIVACY.md: local data, prompt, and hook privacy model
• CONTRIBUTING.md: contribution workflow
• .dev/: AI-authored drafts, design spikes, research notes, and unapproved plans
• docs/: human-reviewed promoted documentation

License

MIT. See LICENSE.