inkwell-memory CLAUDE.md

CLAUDE.md — inkwell_memory

MCP server providing persistent memory for AI agents. Markdown files are the source of truth; a hybrid SQLite FTS5 + semantic embedding index (fused via Reciprocal Rank Fusion) provides search, plus graph-style relations (kb://uuid#type links).

Layout

• src/server.py — MCP tool definitions (remember, recall, search, list, tags, forget, rebuild, doctor)
• src/schema.json + src/schema.py — the entry taxonomy as data: per-type required/body/membership/usage_boost/digest_on_recall. Loader resolves <data-path>/schema.json → packaged default, full replacement, never a merge; builds the entry_type enum injected into server.py's module globals before tool registration (PEP 563 annotations resolve there), so an undeclared type is rejected client-side. Read once at startup → editing it requires a restart.
• src/doctor.py — schema-driven integrity pass (run_doctor), shared by the doctor tool, rebuild's warnings, and remember's conformance warnings via check_entry. Reads the Markdown files, not the index.
• src/database.py — entry storage: Markdown + YAML frontmatter CRUD, UUID assignment
• src/search_backend.py — SQLiteBackend (index, unindex, search, rebuild, get_relations, get_all_relations) + kb:// relation extraction. search fuses BM25 (FTS5) with cosine similarity over local Model2Vec embeddings (_bm25_search + _vector_search + _rrf_fuse); embeddings are stored as a BLOB column on entries and computed lazily/in batch by the same code path that writes the row.
• src/dashboard/ — web dashboard: FastAPI app (app.py, create_app(kb)) exposing REST CRUD + /api/graph over the same KnowledgeBase/SQLiteBackend the MCP tools use (no protocol duplication), a single static index.html (vanilla JS force-directed canvas graph, no build step/CDN) served at /, and __main__.py as its own uvicorn entry point (INKWELL_DASHBOARD_HOST/INKWELL_DASHBOARD_PORT, default port 8193). Runs as a second process in the same container via docker-entrypoint.sh, alongside server.py's MCP process. Single-KnowledgeBase only — not yet multi-tenant-aware (see below).
• src/team_admin.py — TeamAdminStore: SQLite registry (<data_path>/admin.db) mapping a team name to its data folder (<data_path>/teams/<name>/) and a SHA-256-hashed API key. Only touched in multi-tenant mode.
• src/admin_api/ — loopback-only FastAPI app (app.py, create_app(store, api_key)) for add-team/list-teams/revoke-team, guarded by INKWELL_ADMIN_API_KEY; __main__.py is its own uvicorn entry point (INKWELL_ADMIN_API_HOST/INKWELL_ADMIN_API_PORT, default port 8194, not proxied/exposed). Third process in the container, started only when INKWELL_MULTI_TENANT=1.
• src/cli.py — inkwell console script (installed via pyproject.toml's [project.scripts], pip install -e . in the Dockerfile): thin urllib-based HTTP client to admin_api for add-team/list-teams/revoke-team, plus a backup subcommand (on-demand tar.gz of teams//admin.db to a given --dest, no rotation/schedule built in). Run via docker exec <container> inkwell <command>; reads INKWELL_ADMIN_API_URL/INKWELL_ADMIN_API_KEY from the same container environment the admin API itself uses.
• tests/ — mirrors src/ (test_server.py, test_database.py, test_backends.py, test_dashboard.py)