Knowledge and Memory Management: Directions 1-3 Finalized

We’ve just closed the documentation cycle for Directions 1 through 3 in the Knowledge and Memory Management project. This marks a concrete baseline for systems that need to persist, recall, and apply learned information over long interactions. No fluff, no theoretical sandboxes — these directions define the core substrate that agents and applications use to decouple knowledge from transient execution. Here’s what shipped. Direction 1 — Knowledge Ingestion and Structuring The first direction nails down how raw information enters the system. We settled on a three-phase pipeline: chunking, embedding, and triple extraction. Chunking uses a fixed-length token window with overlapping sections to preserve context across boundaries. Embedding ties into a primary vector model (configurable, default is a local ONNX-exported encoder). Triple extraction is optional but powerful: we parse subject-predicate-object triples for exact relational queries. The doc finalization records the decision to keep these three subsystems independent — you can swap any without altering the others. Direction 2 — Memory Indexing and Retrieval This direction defines the two-tier storage: a persistent vector index (using HNSW) and a volatile short-term buffer. The buffer holds the last N interaction turns and is always available for zero-latency recall. The vector index handles long-term similarity search, with a composite key of agent ID + namespace so multitenant systems stay clean. The finalization clarified that retrieval must return ranked candidates with confidence scores, not raw vectors. That forced us to formalize a reranking interface. Direction 3 — Context Assembly for Decision Making The most debated piece. Direction 3 answers how a subsystem selects which memories to surface at runtime. We implemented a two-stage selector: first, a relevance filter (cosine threshold), then a utility predictor that estimates how useful each candidate is for the current task. The doc records that the utility predictor is a lightweight model trained on logged feedback, not handcrafted rules. This direction also defines the concept of a “situation snapshot” — a compact representation of current state that the memory collector uses as query input. Code Example — Memory Retrieval with Reranking Here’s a minimal example using the finalized APIs in Python. It demonstrates retrieval from the vector index followed by utility reranking. from kmm.memory import Index, ShortTermBuffer from kmm.select import UtilityReranker # Initialize the long-term index (HNSW, already loaded) index = Index.load("/models/agent_v3.index") buffer = ShortTermBuffer(capacity=10) # Build a query from current state (simplified) situation_snapshot = { "agent_id": "asst-42", "namespace": "production", "recent_tokens": ["client", "requested", "rollback", "to", "v2.1"] } # First pass: vector similarity candidates = index.search( query_embedding=encode(situation_snapshot["recent_tokens"]), agent_id="asst-42", top_k=20 ) # Rerank by predicted utility reranker = UtilityReranker(model_path="/models/utility.onnx") final = reranker.select(candidates, situation_snapshot, max_results=5) for memory in final: print(f"Memory {memory.id} confidence={memory.confidence:.2f} utility={memory.utility:.3f}") Enter fullscreen mode Exit fullscreen mode The Index.search returns candidates with confidence scores from the cosine distance. The UtilityReranker then overwrites the score with a utility estimate. The short-term buffer is checked alongside this call but omitted for brevity. What This Means for Builders With Directions 1-3 documented and finalized, the implementation surface is stable. You can now depend on the pipeline for ingestion, the two-tier index for recall, and the context selector for memory-aware actions. The code example above highlights the retrieval path — the exact API we’ll support moving forward. The next push will cover Direction 4 (Memory decay and consolidation) and Direction 5 (Cross-session persistent graph). Until then, these three directions form the practical core. The documentation is in the repository under docs/directions/1-3-final. Experienced teams should be able to integrate the core interface in an afternoon.