0CompactMem
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:
/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.
Related MCP server: mnemos
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 automaticallyThe 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 |
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 |
| 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/vMemManual install.
git clone https://github.com/soolaugust/vMem
cd vMem
pip install -e .
mkdir -p ~/.claude/memory-osDetailed 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
# stable test subset
python3 -m pytest tests/test_agent_team.py tests/test_chaos.py -qCoverage: 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 |
| 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.
Context compaction is the #1 productivity killer in Claude Code. vMem makes it a non-event.
Available Tools
5 toolslist_pinnedA
列出当前项目中所有 pinned chunks。
OS 类比:/proc/[pid]/smaps 中 Locked: 字段 — 查看进程的 mlock 区域。
Args:
pin_type: 过滤类型 'hard'/'soft'(默认显示全部)
project: 项目 ID(默认自动解析当前目录)
Returns:
格式化的 pinned chunk 列表
Inputs: pin_type, project. Returns: result
memory_lookupA
在 AIOS 知识库中主动检索相关记忆(推理中断 / demand paging)。
当你推理时发现需要某类知识但不确定时,调用此工具:
- 上次关于某模块的决策
- 某功能的已知设计约束
- 某段代码的参数格式
- 之前总结的性能数据
Args:
query: 查询字符串(自然语言或关键词均可)
top_k: 返回结果数量(默认 5)
chunk_types: 可选,过滤 chunk 类型(如 ["design_constraint", "decision"])
project: 可选,指定项目 ID(默认自动推断)
Returns:
格式化的检索结果,包含 summary 和 content 摘要
Inputs: query (required), top_k, chunk_types, project. Returns: result
memory_statsB
查询 AIOS 知识库的统计信息(chunk 数量、类型分布、近期活跃度)。
Returns:
知识库统计摘要
Inputs: project. Returns: result
pin_memoryA
将指定 chunk 锁定到当前项目,阻止被自动淘汰。
OS 类比:mlock(addr, len) — 将页面锁定在进程地址空间,阻止 swap out。
pin_type:
'hard' — 所有淘汰路径跳过该 chunk(stale reclaim、DAMON DEAD、kswapd ZONE_MIN)
适用:设计约束、不可变决策、关键架构知识
'soft' — 保护 stale reclaim 和 DAMON DEAD,但 kswapd 内存极度紧张时仍可淘汰
适用:重要但非关键的量化证据、近期决策
Args:
chunk_id: 要锁定的 chunk ID(可从 memory_lookup 结果中获取)
pin_type: 'hard' 或 'soft'(默认 'soft')
project: 项目 ID(默认自动解析当前目录)
Returns:
操作结果描述
Inputs: chunk_id (required), pin_type, project. Returns: result
unpin_memoryA
解除 chunk 在当前项目中的 pin,允许被自动淘汰。
OS 类比:munlock(addr, len) — 解除内存锁定,页面重新可被 swap out。
Args:
chunk_id: 要解锁的 chunk ID
project: 项目 ID(默认自动解析当前目录)
Returns:
操作结果描述
Inputs: chunk_id (required), project. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: listing pinned chunks, retrieving memories, showing stats, pinning, and unpinning. No overlaps or ambiguities.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_pinned, pin_memory). No mixing of conventions.
With 5 tools, the set is well-scoped for a focused memory management server. Each tool serves a necessary function without redundancy.
The tools cover the core operations for managing pinned memory: listing, searching, statistics, pinning, and unpinning. Minor gaps like a tool to view all chunks or delete chunks exist, but the primary use case is well-covered.
Maintenance
Related MCP Connectors
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Related MCP Servers
- AlicenseAqualityBmaintenancePersistent memory with knowledge graph visualization, semantic/hybrid search, importance scoring, and cloud sync (S3/R2) for cross-session context management.44750MIT
- AlicenseBqualityCmaintenancePersistent memory engine for AI coding agents. Single Go binary, zero runtime dependencies, MCP-native. Stores, searches, and deduplicates memories across sessions using embedded SQLite with hybrid FTS + semantic search, memory decay, relation graph, and token-budget context assembly.1023MIT
- AlicenseNot gradedqualityBmaintenancePersistent semantic memory for AI agents — hybrid SQLite + FTS5 with DAG-based summaries, context compaction, and 7 MCP tools. Open source, self-hosted, zero API cost.161MIT
- AlicenseNot gradedqualityBmaintenancePersistent memory for AI coding agents that stores and recalls preferences, decisions, and conventions via semantic similarity, with zero cloud dependencies and plug-and-play MCP integration for Claude Code.Apache 2.0