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}")

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.