Knowledge-and-Memory-Management: Direction 1-3 Finalization Record

The Knowledge-and-Memory-Management module has officially finalized Directions 1-3, closing the first phase of our agent cognition framework. This update locks down the core API and behavior for memory persistence, retrieval, and lifecycle management. If you’re building agents that need long-term context without blowing up your token budget, these directions define the primitives you’ll work with daily. Here’s what changed and why.

Direction 1—Memory Persistence—moves from in-memory only to a hybrid SQLite-backed store with optional compression. The finalized schema uses a two-table design: one for raw payloads (JSON blobs with metadata), another for inverted indices of embedding vectors. This avoids the serialization overhead of prior prototypes while keeping atomic writes for concurrent access. The key consequence is that agents can now survive restarts without replaying entire conversation logs. The StorageBackend interface is frozen; custom backends must implement append, query, and vacuum. Expect sub-millisecond writes for small payloads and linear scan for retrieval when indices aren’t available. We’ve included a batch insert method for bulk ingestion of knowledge triples.

Direction 2 tackles retrieval latency with a two-tier index structure. Tier 1 is an LSH-based approximate nearest neighbor index for embedding similarity—good for quick recall of semantically similar memories. Tier 2 is a deterministic B-tree keyed by timestamp and importance score; this handles exact temporal queries. The finalization introduces a RetrievalModes enum: SEMANTIC, TEMPORAL, or HYBRID. In hybrid mode, the system retrieves top-K from Tier 1, then re-ranks using Tier 2’s decay factor. This combined access pattern cuts average query time by 60% compared to brute-force cosine similarity on the full memory pool. The trade-off is a 10% increase in memory index size, but for most workloads that’s negligible.

Direction 3 defines memory lifecycle hooks: on_store, on_access, on_decay, and on_prune. These are synchronous callbacks that fire without blocking the main thread—they simply enqueue side effects. The finalized DecayPolicy accepts a lambda with signature (memory_entry, current_time) -> float. A default exponential decay with configurable half-life is provided. Custom policies can implement temporal recency, importance scoring, or even learned relevance via a small model. The PruningStrategy enum now supports FIFO, LOWEST_SCORE, or HYBRID (a mix of both after 10% capacity overflow). This lets you balance between keeping recent ephemeral context and retaining valuable long-term knowledge.

Here’s a concrete example from the finalized API, showing how to set up a memory manager with a custom decay function:

from knowledge_memory import MemoryManager, DecayPolicy

def custom_decay(entry, t):
    hours_old = (t - entry.timestamp) / 3600
    recency = 1.0 / (1 + hours_old)
    importance = entry.metadata.get("importance", 0.5)
    return 0.7 * recency + 0.3 * importance

manager = MemoryManager(
    storage_path="./agent_mem.db",
    decay_policy=DecayPolicy(custom_decay),
    prune_at=0.85  # prune when capacity hits 85%
)

manager.store(
    payload={"intent": "book_flight", "params": {"origin": "SFO"}},
    embedding=[0.1, -0.3, 0.7],
    metadata={"importance": 0.9}
)

result = manager.query(
    vector=[0.15, -0.25, 0.65],
    mode="hybrid",
    top_k=5
)

The store method writes atomically to the SQLite backend and updates both index tiers. The query method returns a list of MemoryEntry objects with scores. The callback on_store would fire before the write completes, enabling you to log or stream memory creation events.

For experienced developers, the main takeaway is that Direction 1-3 finalization locks in the contract between your agent logic and the memory substrate. No more chasing unstable APIs across versions. You can now build state machines, conversational loops, or task planners on top of this foundation with confidence that the memory layer won’t silently drop context or fail on edge cases like concurrent writes or corruption.

Planned next steps for Directions 4-6 include distributed memory sharding, direct graph traversal over knowledge triple stores, and learned retention policies via reinforcement learning. But for now, Direction 1-3 is solid. Update your dependencies, review the migration guide from the v0.4.x to v0.5.x changelog, and start leveraging the new lifecycle hooks to prune aggressively. This finalization record is also the basis for the API reference in the docs—every method and parameter signature is now stable and will not change until a major version bump.

The Knowledge-and-Memory-Management module now provides a predictable memory substrate. Use it to give your agents the ability to forget gracefully and recall precisely. That’s the difference between a script and an agent that learns.