Inkwell

Inkwell — Persistent Knowledge Base MCP Server

Inkwell is a self-hosted Model Context Protocol server that gives AI agents persistent memory across sessions and projects. Three things set it apart from the other memory servers: plain Markdown files are the source of truth (the index is a throwaway cache you can delete and rebuild), entries are connected by a typed `kb://` graph rather than dumped into a flat pile, and updates are bi-temporal — superseding a fact keeps the old version readable instead of overwriting it.

Docker Hub: foreigndmitryi/inkwell-memory · Website: veronchenko.github.io/inkwell-memory

Formerly Engram. Renamed in 0.14.0 — there are a dozen unrelated projects called "Engram" and the name had stopped being findable. Not affiliated with any of them, nor with the Engram keyboard layout. See the changelog for what the rename breaks.

Table of Contents

• Concept
• Features
• Comparison
• Measured Against a Plain Markdown Wiki
• Design Patterns
• Architecture
• Quick Start
• Search
• Tools
• Dashboard
• Graph Relations
• Usage Examples
• Prompt Your Agent
• Configuration
• Storage Format
• Development
• License

Concept

Agent conversations end and take their context with them. Inkwell is the piece that survives: a knowledge base an agent searches *before* acting and writes to *after* resolving something non-obvious, so the next session — same project or a different one — starts with what was already learned instead of re-deriving it.

It deliberately stores zero discoverable information. If a fact can be pulled from code, git history, config files, or existing docs, it does not belong in Inkwell — that's what greps and re-reads are for. What belongs is the kind of knowledge a conversation would otherwise lose: a decision and the alternatives it ruled out, a bug's root cause and fix, a procedure learned the hard way, a preference stated once that should hold from then on.

Two things keep the base usable as it grows:

• Atomicity — one entry, one fact. remember warns (non-blocking) on Markdown headers, more than 3 paragraphs, or content past 512 B/1 KB, pushing multi-fact dumps back into separate linked entries instead of a wall of text no search will rank well.
• The graph, not a pile — entries link to each other via kb://uuid#type references, so related facts (a hub project, its features, a diagnostic tied to one of them) stay navigable both ways instead of living as isolated rows.

Features

• Hybrid search — SQLite FTS5 (BM25, Porter stemming) fused with cosine similarity over local Model2Vec embeddings *and* an IDF-weighted exact-match channel over title/tags via Reciprocal Rank Fusion; finds entries by meaning or by a literal proper noun BM25/embeddings alone would dilute among lexically-similar distractors, with zero cloud dependency
• Typed graph relations — kb://uuid#type links between entries, resolved both directions (outgoing + backlinks) on every recall, with an optional second hop (hops=2) to see how two entries connect through an intermediate one
• Schema-enforced entry types — hub, decision, diagnostic, feature, procedure, integration, pattern, snippet, preference, idea — declared in schema.json and exposed to the client as an enum, so an invalid type can't be written; filterable on search/list
• `doctor` integrity pass — one schema-driven check over the Markdown files for dangling and superseded links, undeclared types, missing template fields, supernodes, and tag/type collisions
• `part_of` structural membership — links a detail entry (decision, diagnostic, feature, procedure, integration, ...) to its hub, enforced per type by the schema; filterable on search/list, grouped alongside kb:// back-links in a hub's recall digest
• Bi-temporal versioning — remember(..., supersede=True) creates a new version instead of overwriting; old versions stay in history (include_superseded=True) instead of being lost
• Duplicate detection & link suggestions — remember matches near-identical titles to avoid duplicate entries, and returns suggested_links (embedding-similarity matches) so related facts get cross-referenced instead of orphaned
• Atomicity guardrails — non-blocking warnings on structural anti-patterns (headers, >3 paragraphs, oversized content) so the base stays one-fact-per-entry as it scales
• Web dashboard — force-directed graph view, hybrid search, and a CRUD panel over the same knowledge base the MCP tools use (see Dashboard)
• Three transports — stdio (agent-managed), SSE, streamable-http — so the same server works for a single local agent or a shared multi-agent deployment
• Markdown as source of truth — the SQLite index is a rebuildable cache; delete it and rebuild, no data is ever lost

Comparison

Inkwell trades automatic extraction (Mem0, Zep) for an agent-curated, atomic, explicitly-linked knowledge base — no LLM-driven ingestion pipeline, no graph database dependency, and the on-disk Markdown stays human-readable and diffable.

Measured Against a Plain Markdown Wiki

Inkwell was benchmarked against the same knowledge base packaged as an ordinary Markdown wiki — one file per topic, organized in folders by project and category (decision, diagnostic, feature, procedure, ...), each project with an index page and cross-links between related pages, browsed with Read/Grep/Glob/Bash. Same content, two ways of finding it — for equivalent fact coverage, Inkwell's search/recall used:

32 questions (single-hop, multi-hop, negative, cross-lingual, supersede) over 5,070 entries — 70 curated facts across 4 fictional projects plus 5,000 real-text distractor entries, so retrieval has to work at a scale that doesn't fit in an agent's context:

wiki/

├── Ledgerbird/ ) ├── Pipewren/ ) 4 curated projects — 70 real ├── Snipfox/ ) decisions/diagnostics/features/ ├── Featherstore/ ) procedures/integrations/snippets │ ├── README.md <- project index page, links to every entry below │ ├── decision/ │ │ ├── offline-engine-duckdb-over-spark.md │ │ ├── online-value-serialization-msgpack.md │ │ └── ... (2 more) │ ├── diagnostic/ │ │ ├── redis-memory-doubling-from-ttl-less-deprecated-feature-groups.md │ │ └── training-serving-skew-from-tz-naive-event-timestamps.md │ ├── feature/ (4 entries) │ ├── integration/ (2 entries) │ ├── procedure/ (1 entry) │ └── snippet/ (1 entry) ├── _shared/ cross-project patterns & preferences └── haystack-project-00000.../00199/ 200 distractor projects x 25 pages │ = 5,000 real-text (Wikipedia) pages ├── README.md <- same index-page shape as a real project ├── decision/ (2 entries) ├── feature/ (3 entries) ├── idea/ (7 entries) ├── pattern/ (4 entries) ├── procedure/ (1 entry) └── snippet/ (2 entries)

Every category folder is a flat list of one-file-per-entry, and every project folder (real or distractor) has its own README.md index page linking to all of them — structurally identical, so the wiki arm can't tell curated fact from distractor by shape alone.

An agent that already knows *where* to look doesn't need to grep, re-read, and re-grep its way there — the efficiency edge holds for equivalent fact coverage. Retrieval ranking has also been improving: adding an IDF-weighted exact-match channel (below) moved MRR from 0.851 to 0.857 and recall@5 from 0.851 to 0.869, with no regression across any language.

Design Patterns

• Reciprocal Rank Fusion — BM25 and embedding rankings are computed independently and merged by rank position rather than raw score, avoiding the need to normalize incomparable similarity metrics.
• Rebuildable cache over source of truth — the SQLite index is fully derived from the Markdown files (rebuild regenerates it from scratch); the database is never the only copy of a fact.
• Bi-temporal versioning — supersede writes a new entry and points the old one at it via superseded_by, instead of overwriting in place, so history stays queryable (include_superseded).
• HATEOAS-style graph traversal — every recall response carries its own outgoing/incoming kb:// links, so navigating the knowledge graph doesn't require a separate query per hop.
• Shared domain layer, two transports — the dashboard's REST API and the MCP tools both call the same KnowledgeBase/SQLiteBackend methods, so there is exactly one code path for writes regardless of which surface triggered them.

Architecture

Markdown files  --->  Search index  --->  MCP  --->  Agent

(source of truth) (SQLite FTS5 + (server.py) (Claude Code, Model2Vec, ChatGPT, ...) rebuildable cache)

Markdown files in /entries/ are the only source of truth. The SQLite index (search_backend.py) is a disposable cache built from them — BM25 + Model2Vec embeddings fused via Reciprocal Rank Fusion, plus the kb:// relation graph — and can always be regenerated with rebuild. server.py exposes that index to an agent as MCP tools (remember/recall/search/...); the dashboard is an alternate entry point at the same layer, hitting the same KnowledgeBase/index directly over REST instead of MCP, so remember/delete behave identically whether called by an agent or edited by hand in the browser.

• `src/server.py` — MCP tool definitions (remember, recall, search, list, tags, forget, rebuild, doctor), one process, stdio/SSE/streamable-http transport
• `src/database.py` — KnowledgeBase: M