Hollow

v2.0.0 — Semantic Memory

The foundation for Phase 3: agent-native cognition.

Replace key-value storage with vector-native memory. Every object is stored as an embedding. Retrieval by cosine similarity, not key lookup.

How it works

An agent stores a thought: embed("the rate limiter failed at 3AM because bucket depth was wrong"). Later it searches: embed("what went wrong with rate limiting") and memory surfaces automatically by semantic distance.

Memory now matches agent cognition. No naming schemes. No schema management. Pure semantic.

API

• store(agent_id, thought: str, metadata: dict) → memory_id
• search(agent_id, query: str, top_k=5, threshold=0.7) → list[MemoryRecord]
• recall(agent_id, memory_id) → MemoryRecord
• forget(agent_id, memory_id) → bool
• consolidate(agent_id) → int (merge similar memories, compress old ones)
• list_agent_memories(agent_id, limit=50) → list[MemoryRecord]

Storage

• Per-agent memory stored in /agentOS/memory/semantic/{agent_id}/
• Embeddings as NumPy arrays (embeddings.npy)
• Metadata as JSONL (metadata.jsonl)
• Index mapping memory_id → row index (index.json)
• LRU capacity management: evicts least-recently-accessed memories when limit exceeded

Made possible by

• v1.0.0 (working memory heap) — provides the eviction policy pattern
• v1.3.3 (checkpoints) — memory survives across agent restarts

Tests

7/7 integration tests passing. All tests hit live embedding model (sentence-transformers) with real semantic search, no mocks.