Local-first shared memory hub for AI agents.

This project stores long-lived agent memory on your machine and exposes it through a CLI and a local MCP server. SQLite is the source of truth, Markdown is the readable vault/export layer, and semantic search is left behind a local embedding interface that can be enabled later.

• Node.js 22 or newer
• pnpm
• sqlite3 CLI

The runtime has no npm dependencies. The TypeScript files run directly with Node 22's --experimental-strip-types.

pnpm test
node --experimental-strip-types src/cli/index.ts init
node --experimental-strip-types src/cli/index.ts add --type preference --scope public --tag coding "Prefer small focused commits."
node --experimental-strip-types src/cli/index.ts search "focused commits"

Default data lives in:

~/.agent-memory/
  memory.db
  config.yaml
  audit.log
  vault/
    profile.md
    preferences.md
    decisions.md
    people.md
    inbox.md
    projects/

For tests or isolated usage, set:

AGENT_MEMORY_HOME=/tmp/agent-memory-demo node --experimental-strip-types src/cli/index.ts init

agent-memory init
agent-memory add [options] <content>
agent-memory search [options] <query>
agent-memory list [options]
agent-memory update <id> [options] [content]
agent-memory archive <id> [reason]
agent-memory delete <id> [reason]
agent-memory export-md [directory]
agent-memory import-md [directory]
agent-memory import-local --source <file|directory|claude-code|openclaw|generic> --path <path>
agent-memory bootstrap --agent codex --scope public,work --project agent-memory
agent-memory reindex
agent-memory audit [memory_id]

Common options:

--type <preference|fact|project|decision|person|task|note>
--scope <public|work|personal|project:name|secret>
--sensitivity <public|work|personal|secret>
--tag <tag>              repeatable or comma-separated
--limit <number>
--json

The MCP server is local stdio only:

node --experimental-strip-types /Users/zheng/Projects/agent-memory/src/mcp/server.ts

Tools:

memory.search
memory.search_index
memory.get
memory.timeline
memory.bootstrap
memory.import_local
memory.add
memory.update
memory.archive
memory.delete
memory.propose
memory.audit

memory.search and memory.search_index return lightweight index entries. Fetch full content with memory.get after selecting a relevant id.

Content inside <private>...</private> is stripped before memory is persisted, indexed, exported, or written to audit snapshots.

See examples/mcp/ for client snippets.

Use bootstrap to initialize any local agent session from shared memory:

agent-memory bootstrap --agent codex --scope public,work --project agent-memory

The MCP equivalent is memory.bootstrap. Agents should call it at session start, then use memory.get only for records that need full context.

Use the generic importer for any local app that can expose files or transcripts:

agent-memory import-local --source directory --path /path/to/app/history --scope work --dry-run
agent-memory import-local --source directory --path /path/to/app/history --scope work

Claude Code JSONL transcripts can be imported with:

agent-memory import-local --source claude-code --path ~/.claude/projects --scope work --tag claude

OpenClaw can be imported directly. If --path is omitted, it defaults to ~/.openclaw:

agent-memory import-local --source openclaw --dry-run
agent-memory import-local --source openclaw --scope work --tag openclaw

The OpenClaw adapter reads workspace/MEMORY.md, workspace/memory/**/*.md, and agents/*/sessions/*.jsonl. It skips trajectory, checkpoint, reset, deleted, config, credential, media, and plugin dependency files.

OpenCode, KiloCode, Codex, and other local apps should integrate through the same memory.import_local tool or CLI command. If an app stores history in a custom format, add a small adapter under src/importers/ and keep the output as ImportCandidate[].

Agent permissions live in ~/.agent-memory/config.yaml.

agents:
  codex:
    read: ["public", "work", "project:*"]
    write: ["project:*", "decision", "note"]
    denied: ["secret"]

The first implementation applies read filtering for MCP calls. CLI commands are treated as direct local owner access.

Back up the whole directory:

tar -czf agent-memory-backup.tgz ~/.agent-memory

You can also export a readable vault:

agent-memory export-md

• Local storage by default.
• SQLite is the authoritative store.
• FTS5 powers keyword search.
• Markdown export/import keeps the memory human-readable.
• Embeddings are local-only by design and currently stubbed behind reindex.
• MCP uses the same core service as the CLI.