agentmemdb 0.1.0

Local-first, shared long-term memory for AI agents.
One SQLite database, served over MCP, so Claude Code, omp and every other agent on your machine remember the same things.

Getting started · Examples · Configuration · Tools · Architecture

AI agents forget everything when a session ends, and different agents never see what the others learned. agentmemdb gives them one long-term memory: a local SQLite file, exposed as 16 MCP tools, that every agent on your machine reads and writes.

• Shared. What Claude Code saves in the morning, omp can recall in the afternoon. Every write records which agent made it.
• Local. One file on your machine. No cloud service, no API keys, no embedding model, no telemetry.
• Cheap to recall. Ranked full-text search returns short snippets instead of whole memories, so lookups use few tokens.
• Safe with many agents. Concurrent readers and writers, and a failed call can never leave the database locked.

See it in action

You → Claude Code   We're moving billing-api from MySQL to Postgres 17 for row-level security. Remember that.

      save_memory   {"topic": "billing-api: move from MySQL to Postgres 17", "category": "decision", "importance": "high", …}
                  ← {"status": "saved", "id": 1, "tags": "billing,database", "auto_tags_added": ["database"]}

You → omp           (next day) Why are we moving billing to Postgres?

      search_memory {"query": "why are we moving billing to postgres"}
                  ← {"count": 1, "results": [{"id": 1, "topic": "billing-api: move from MySQL to Postgres 17",
                       "snippet": "…we need row-level security to isolate merchants, which MySQL does not offer…"}]}

The examples walk through the full session: appending from a second agent, attribution, duplicate warnings, threads and entities, with real responses.

Quick start

Install it with any of these (macOS or Linux, Python 3.10+):

brew install harsh-gulhane/tap/agentmemdb   # Homebrew
pipx install agentmemdb                     # or: pip install agentmemdb
uvx agentmemdb --check                      # or run it without installing, with uv

agentmemdb --check shows where the database and config will live. Then connect your agents, using the server name memory everywhere so tool names match across clients (with uv, replace agentmemdb with uvx agentmemdb):

# Claude Code
claude mcp add memory -s user -- agentmemdb

// omp: ~/.omp/agent/mcp.json
{ "mcpServers": { "memory": { "type": "stdio", "command": "agentmemdb" } } }

Claude Desktop, Cursor, VS Code, Codex and HTTP setups are in getting started. To have agents save and search without being asked, add the memory policy prompt to your CLAUDE.md or AGENTS.md.

Features

• Relevance search. SQLite FTS5 with stemming and BM25 ranking, where topic and tag matches rank highest. Handles IDs and names like OPS-2406, PR #3056 and example.com, plain questions, and partial words.
• Structured memories. Categories, importance levels, tags, threads, entities (people, services, repos, tickets) and expiry dates.
• Automatic tags. Regex rules in the config tag matching memories, e.g. anything mentioning Postgres or MySQL gets database.
• Safe edits. Duplicate warnings on save, append mode, and an edit history that keeps replaced content.
• One policy for every agent. Instructions in the config file reach every connected client's system prompt.
• stdio or HTTP. One process per client, or one shared server over streamable HTTP on localhost.

Tools

Parameters and behaviour: tool reference.

Configuration

Optional. ~/.config/agentmemdb/config.json:

{
  "db_path": "~/.local/share/agentmemdb/memory.db",
  "auto_tags": { "database": "postgres|mysql|sqlite", "incident": "incident|outage" },
  "instructions": "Search memory before answering questions about past work."
}

Environment variables, path resolution, sharing and backups: configuration.

Development

git clone https://github.com/harsh-gulhane/agentmemdb && cd agentmemdb
make install    # uv sync: editable install plus dev tools
make check      # ruff, mypy --strict, pytest

See CONTRIBUTING.md for the project layout and workflow.

Security

agentmemdb stores memories unencrypted in a local file and makes no network calls. Read SECURITY.md for the security model, and report vulnerabilities privately through GitHub security advisories.

License

MIT © Harsh Gulhane