localmem-mcp: Instructions file for Claude Code

CLAUDE.md

Project context for agent sessions working on this repo.

What this is

localmem-mcp gives AI agents persistent memory that never leaves the user's machine. It ships as both an MCP server and an importable Python library.

The whole pitch is one sentence: local-first, zero-API memory for AI agents — no cloud calls, no API keys, no per-call billing. Every change should keep that sentence true.

Non-negotiables

1. No network calls at runtime. The single exception is fastembed's one-time model download on first use. Do not add telemetry, analytics, update checks, or any hosted service dependency.
2. No API keys. If a feature needs a key, it doesn't belong here.
3. Single-purpose. This is a memory tool. Resist scope creep into agent frameworks, RAG pipelines, or chat UIs.
4. Install-to-working under 30 seconds. Weigh every new dependency against that. fastembed was chosen over sentence-transformers precisely for install size and cold-start time — don't swap it back.
5. New task, new branch, new PR. Never continue an existing PR's branch to do unrelated work. See Branching and PRs.

Layout

The code is organized into three implementation packages, each fronted by a backward-compatible facade module so the documented import paths (localmem_mcp.store, .server, .cli) never change as internals grow.

src/localmem_mcp/
  core/       Data layer. MemoryStore — SQLite schema, embeddings, hybrid
              search. The core of the project.
    models.py     Memory, SearchResult records
    embedders.py  Embedder protocol, FastEmbedEmbedder, DEFAULT_MODEL
    schema.py     _SCHEMA DDL + FTS5 sync triggers
    search.py     _cosine, _fts_query, KEYWORD_WEIGHT
    portability.py  JSONL import: import_records, ImportReport
    utils.py      tag/vector/row helpers, default_db_path, _days_ago
    store.py      MemoryStore class
  mcp/        MCP server. app.py (FastMCP instance + store lifecycle) and
              tools.py (thin wrappers over MemoryStore; tool docstrings are
              the agent-facing UX — they matter as much as the code).
  commands/   CLI. parser.py (argparse), handlers.py (per-command logic),
              main.py (dispatch). `localmem-mcp` with no args runs the server.
  store.py    facade re-exporting core/     (stable import path)
  server.py   facade re-exporting mcp/      (stable import path)
  cli.py      facade re-exporting commands/ (console entry point)
tests/
  test_store.py   store behaviour, against a deterministic stub embedder
  test_server.py  MCP tools end-to-end via fastmcp's in-memory Client
benchmarks/   run.py — add/search latency harness; RESULTS.md — committed numbers
docs/         MkDocs Material site, published to GitHub Pages from main
mkdocs.yml    site config