soolaugust/0CompactMem

**Virtual memory for LLM context. For Claude Code and every AI agent.**
*Your AI never forgets — no more "context compacted" interruptions.*
English · 中文
> **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 **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:
1. **Hooks** — sit at the Claude Code syscall boundary (SessionStart, UserPromptSubmit, Stop, PostToolUse) and call into the store.
2. **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).
3. **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.