Documents aren't memories
When you first wire up a memory layer, there is an obvious temptation: point it at your docs folder and let it eat. The wiki, the runbooks, the design notes. If the agent can recall a decision, surely it can recall a document. It is the same impulse that makes people reach for a vector database for everything, and it quietly produces a worse system.
A curated memory and a document are different things, and memkeeper treats them differently on purpose.
What a memory is
A memory in memkeeper is atomic. One idea, written to stand on its own with its context intact: "staging has mirrored prod since the March migration," not a paragraph that happens to mention staging. That grain is what makes the rest of the engine work. Atomic memories can be deduplicated, superseded when they change, linked into an entity graph, and promoted to a durable tier when they prove useful. Retrieval is sharp because each result is a complete thought.
Dump a whole document into that tier and the machinery breaks. There is no chunking, and the local embedder only sees the start of a long entry, so semantic recall degrades to whatever sat near the top. Keyword search still indexes the full text, but you have traded a precise memory for a fuzzy one. It works mechanically and disappoints in practice.
A separate tier for documents
So memkeeper keeps documents in their own space. The memkeeper-ingest add-on walks a folder, chunks each file with structure in mind (heading breadcrumbs kept, code blocks not split on blank lines, front-matter stripped), embeds the chunks, and stores them isolated from the curated tier. Search over them is hybrid: BM25 and vector results fused, and every hit carries a citation back to its source file and chunk. No model generates anything in the ingest path. It is retrieval, not generation.
Reference material should not rewrite your memories. Ingested chunks deliberately receive none of the memory treatment: no dedup, no supersession, no graph, no promotion. They sit in their own space so that loading a folder of docs can never quietly reshape the durable facts you have curated by hand.
The bridge runs one way
The two tiers are not walled off. Documents can earn their way into memory through promotion. A chunk that keeps surfacing in real searches is a candidate, and so is one you point at by hand. Promotion can distill the chunk into an atomic memory with a model, or pin it verbatim with no model at all, and the result can wait in a review queue or land directly. The provenance travels with it, so a promoted memory still knows which document it came from. Documents feed memory; memory does not silently absorb documents.
Honest about scope
Today this is markdown-first. The chunker understands headings, code, and front-matter, which covers wikis, runbooks, and repositories well. PDF, HTML, and source-code-aware splitting are future work, not shipped claims. A benchmark harness ships with the add-on so you can point it at your own held-out corpus and measure chunking quality on documents you actually care about, rather than taking a number on faith.
The short version: not everything your agent should be able to look up belongs in its memory. memkeeper draws that line on purpose, and gives you a door between the two sides.