0CompactMem README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the 0CompactMem listing page.
vMem
Virtual memory for LLM context. For Claude Code and every AI agent.
Your AI never forgets — no more "context compacted" interruptions.
One-line install via Claude Code:
The problem: context compaction kills your flow
If you use Claude Code, you know this pain:
Every time this happens, your AI loses track of decisions, constraints, and hard-won context. You re-explain. It re-learns. Hours of accumulated understanding — gone in one compaction event.
And if you run multiple agents? They can't share what they've learned. Each one starts from zero.
This isn't a model limitation. It's a missing infrastructure layer.
The solution: persistent context that survives compaction
vMem gives your AI agents persistent, retrievable context managed like virtual memory: the context window is the hot working set, and durable knowledge lives outside it until demand-paged back in.
The result: OS-managed context continuity. Your AI retains every decision, constraint, and lesson across sessions, across compactions, across agents.
How it works
The whole pipeline runs inside Claude Code hooks. There is no manual memory management.
Why "vMem"?
vMem is virtual memory for LLM context: instead of treating the context window as the whole world, it manages a working set with OS primitives.
| What others see | What vMem does |
|---|---|
| "Context compacted" | Durable knowledge already lives outside the window |
| New session starts | Working set auto-restored in <100ms |
| Multiple agents running | All share one managed context substrate |
| Constraint decided 3 weeks ago | Pinned with mlock-style semantics |
OS-managed context. Durable working sets. No repeated explanation.
Under the hood: OS context management for AI
The secret sauce? We didn't invent new algorithms. We borrowed what the Linux kernel has been doing for 40 years:
| OS concept | vMem equivalent |
|---|---|
| RAM (working space) | Context window — what the AI sees right now |
| Disk (persistent storage) | Knowledge base — facts that survive across sessions |
| Demand paging | On-demand retrieval — fetch relevant memories at the right moment |
mlock | Hard / soft pinning — guarantee a constraint is never evicted |
| kswapd watermarks | Capacity-aware eviction under pressure |
| CRIU checkpoint / restore | Session snapshots — pause and resume seamlessly |
| Process scheduling | Multi-agent coordination — many agents, one knowledge base |
| kworker thread pool | Async extraction — I/O off the critical path |
How is this different from mem0 / Letta / Zep?
| vMem | mem0 | Letta (MemGPT) | Zep | |
|---|---|---|---|---|
| Design metaphor | OS-managed context | Vector store | Agent runtime | Temporal graph |
| Context continuity | ✅ pinned knowledge survives | ❌ | ❌ | ❌ |
| Multi-agent shared | ✅ native, single store | ⚠️ via API | ✅ | ✅ |
| MCP-native | ✅ first-class | ❌ | ❌ | ❌ |
| Single-file deploy | ✅ SQLite, no service | ❌ needs server | ❌ needs server | ❌ needs server |
| Demand-paging retrieval | ✅ explicit | implicit | implicit | implicit |
| Eviction policy | ✅ kswapd + DAMON | TTL only | recency | recency + decay |
| Pin / mlock semantics | ✅ | ❌ | ❌ | ❌ |
TL;DR. If you're tired of context compaction wiping your AI's memory, and you want a solution that's
pip install, runs as a sidecar on a laptop, shares between several Claude Code / Cursor / custom agents, and never loses a pinned constraint — vMem is built for that.
Performance at a glance
| Metric | Value |
|---|---|
| Retrieval latency (P50, hot path) | ~0.1 ms (540x faster than the 54 ms subprocess baseline) |
| Recall@3 vs baseline | +147% |
| Cross-session recall | 94.2% |
| Token cost per call | ~44 tokens injected, +256 tokens net ROI (avoided re-explanation) |
| Test suite | 3,500+ tests across retrieval, eviction, MCP, privacy filter |
Quick start
One-line install (recommended).
Manual install.
Detailed Claude Code hook configuration, daemon management, and troubleshooting live in docs/SETUP.md.
Architecture
Three layers:
- Hooks — sit at the Claude Code syscall boundary (
SessionStart,UserPromptSubmit,Stop,PostToolUse) and call into the store. - Store — single SQLite file (WAL mode) with FTS5 full-text index, behind a unified VFS interface (
memory_os.store.api/memory_os.store.vfs/memory_os.store.criu). - Daemons & IPC — persistent retriever daemon (Unix socket), async extractor pool (kworker-style), cross-agent notify bus.
For the full layered diagram, on-disk schema, and the rationale behind each subsystem, see docs/ARCHITECTURE.md. For the comprehensive OS-and-cognitive-science primitive mapping, see docs/DESIGN_PHILOSOPHY.md.
Roadmap
- Distributed vMem — cgroup-style multi-agent quotas, network-replicated stores
- Adaptive watermarks — eviction tuning that follows observed agent behavior
- arXiv preprint — formal evaluation against mem0 / Letta / Zep
- Per-chunk embedding routing — different models for code vs prose
What landed already (1,051+ tuning iterations, eight major capability rounds) is summarized in CHANGELOG.md. Pain points it has resolved along the way are in docs/PROBLEMS_SOLVED.md.
Testing
Coverage: per-session DB isolation, concurrent-write safety, cross-agent IPC delivery, extractor-pool queue semantics, CRIU checkpoint validation, goals-progress idempotency.
Dependencies
No GPU. No external API. Everything runs locally.
| Dependency | Purpose |
|---|---|
| Python 3.12+ | Core runtime |
| SQLite (built-in) | Store + FTS5 full-text index |
nc, flock | Daemon socket + single-instance startup |
Paper
📄 Beyond Eviction: Full OS Context-Management Semantics for LLM Agent Persistence (PDF, 8 pages)
Technical paper describing the complete OS→agent-context mapping: demand paging, kswapd, DAMON, mlock, CRIU, kworker, and shared memory.
Citation
Contributing
Each subsystem hides behind a clean VFS interface, so components are testable in isolation. Issues, design proposals, and pull requests are welcome — see the Discussions tab for design questions, and please run the test subset above before submitting a PR.