Hollow

What's New

The Invention: Context Window as Managed RAM

An LLM's context window is RAM. No existing system manages it. Agents currently handle their own context blindly — no way to free space, compress old reasoning, or guarantee important information survives long sessions. v1.0.0 introduces the OS primitive with no Unix analogue.

memory/heap.py — WorkingMemoryHeap

• alloc(key, content, priority, ttl, compression_eligible) — allocate a named memory slot with token measurement, priority protection, and optional TTL
• read(key) — retrieve content; auto-swaps-in from disk if swapped; raises KeyError on expired/freed keys
• free(key) — release slot and tokens
• gc() — collect expired (TTL) objects; emits memory.gc_complete
• compress(key) — summarize via mistral-nemo:12b; original saved to disk; emits memory.compressed
• swap_out(key) / swap_in(key) — serialize to disk / restore; emits memory.swapped
• heap_stats() — total_tokens, object_count, compressible_tokens, swapped_count, fragmentation_score
• auto_manage(budget) — at 80% token budget: emit memory.pressure → compress bottom quartile → swap oldest low-priority objects

Priority Tiers

• 0-4 — background, swapped first, compressed first
• 5-7 — normal (default: 5)
• 8-10 — protected; never auto-compressed

New API Endpoints

• POST /memory/alloc
• GET /memory/read/{key} (auto-swap-in)
• DELETE /memory/{key}
• GET /memory (list + stats)
• POST /memory/compress
• POST /memory/swap/{key}
• GET /memory/stats

New MCP Tools (6)

memory_alloc, memory_read, memory_free, memory_list, memory_compress, heap_stats

Total: 57 MCP tools

Events

memory.pressure, memory.compressed, memory.gc_complete, memory.swapped

Integration Tests

6 test classes in tests/integration/test_working_memory.py — alloc/read/free cycle, TTL expiry, compression quality (Ollama only), swap round-trip, heap_stats schema, fragmentation/GC. All auth-enforcement tested.