Knowledge and Memory Management: Finalizing Directions 1-3

The recent doc update for Knowledge and Memory Management finalizes Directions 1–3, locking down the core architecture for persistent context and retrieval. These three directions were previously in draft, and the finalization record removes ambiguity around data lifetimes, indexing strategies, and integration contracts. Here’s what each direction delivers for implementers building stateful reasoning systems.

Direction 1: Core Memory Architecture

This direction defines the canonical memory model. The finalized design separates short-term (ephemeral session buffers) from long-term (durable, decay-weighted storage). The key decision is explicit priority buckets: any memory entry tagged with high_priority bypasses eviction thresholds. This eliminates the earlier ambiguity about whether all entries were subject to LRU pruning.

Implementation now requires a store() call that accepts a priority parameter and a recall() function that takes a query plus an optional threshold for cosine similarity scoring. The example below shows the minimum contract:

class DirectedMemory:
    def __init__(self):
        self._short = []
        self._long = {}
    def store(self, key, data, priority="normal"):
        if priority == "high":
            self._long[key] = data
        else:
            self._short.append((key, data))
    def recall(self, query, threshold=0.6):
        results = [(k, d) for k, d in self._long.items() if self._match(query, k)]
        results += [(k, d) for k, d in self._short if self._match(query, k)]
        return [d for _, d in results if self._score(query, d) > threshold]
    def _match(self, query, key):
        return query.lower() in key.lower()
    def _score(self, query, data):
        # simplified similarity – real impl uses embeddings
        return 0.8 if query in data else 0.2

The finalization mandates that store() must be synchronous in inner loops; async wrappers are optional. This avoids the earlier confusion about when memory writes flush to disk.

Direction 2: Retrieval Pipeline

Direction 2 covers the indexing and query flow. The final version standardizes incremental indexing: new entries are added to the index without full rebuilds. The pipeline now expects a commit call after batch writes, which triggers an in-memory merge before persistence. The doc removes the experimental vector-only mode—all retrievers must also support keyword fallback for deterministic matching. This is critical for debugging and audit trails.

Direction 3: External Integration

Direction 3 defines how external knowledge sources (APIs, databases, file systems) hook into the memory graph. The key finalized feature is the MemoryAdapter interface. Every adapter must implement sync and read primitives, with a required namespace parameter to prevent key collisions across sources. The update also deprecates the auto-merge behavior from Draft 2; adapters now return explicit conflict signals when external data overlaps with stored memory. Handlers receive these as ConflictWarning objects and can apply policy (overwrite, skip, or merge with priority).

These three directions remove the guesswork from earlier iterations. If you built a prototype against the drafts, expect the most pain in Direction 1’s priority semantics and Direction 3’s adapter signature. The finalization record includes a migration guide that maps the old method names to the new ones—worth reading before you update your dependency lock.