One-line install via Claude Code:

/install-plugin github:soolaugust/vMem

---

The problem: context compaction kills your flow

If you use Claude Code, you know this pain:

⚠️ Auto-compact: conversation is approaching context limit...

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

You speak
  → vMem retrieves relevant memories → injects into context
  → AI responds with full context
  → Session ends → decisions and insights auto-extracted → persisted
  → Compaction happens? No problem — memories survive outside the window
  → Next session starts → working set restored automatically

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).

/install-plugin github:soolaugust/vMem

Manual install.

git clone https://github.com/soolaugust/vMem
cd vMem
pip install -e .
mkdir -p ~/.claude/memory-os

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.

---

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

# stable test subset
python3 -m pytest tests/test_agent_team.py tests/test_chaos.py -q

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

@software{su2026compactmem,
  title = {vMem: Full OS Memory Semantics for LLM Agent Persistence},
  author = {Su, Zhidao},
  year = {2026},
  url = {https://github.com/soolaugust/vMem}
}

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.

---