Skip to main content
Glama

vMem

Virtual memory for LLM context. For Claude Code and every AI agent.

Your AI never forgets — no more "context compacted" interruptions.

Python SQLite Tests License Discussions

English · 中文

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


Context compaction is the #1 productivity killer in Claude Code. vMem makes it a non-event.

English · 中文

Available Tools

5 tools
list_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

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing pinned chunks, retrieving memories, showing stats, pinning, and unpinning. No overlaps or ambiguities.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_pinned, pin_memory). No mixing of conventions.

    Tool Count5/5

    With 5 tools, the set is well-scoped for a focused memory management server. Each tool serves a necessary function without redundancy.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Persistent 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.
      10
      23
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Persistent 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.
      161
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Persistent 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