Skip to main content
Glama
soolaugust

0CompactMem

by soolaugust
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 列表
ParametersJSON Schema
NameRequiredDescriptionDefault
pin_typeNo
projectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool returns a formatted list and describes parameters, but does not disclose side effects, authentication needs, or error conditions. The read-only nature is implied by the name but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short paragraphs and a clear 'Args/Returns' section. The OS analogy adds extra context but is not essential, slightly reducing conciseness. Still, it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 optional params, output schema exists), the description covers core functionality, parameters, and return format. It lacks details on project resolution behavior or limitations, but is adequate for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully explains both parameters: pin_type (filter options with defaults) and project (auto-resolve behavior). It adds clarity on allowed values and default behavior, which the schema lacks entirely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: listing all pinned chunks in the current project. The verb '列出' (list) and resource 'pinned chunks' are specific and unambiguous. Although it doesn't explicitly distinguish from sibling tools, the unique resource and operation make the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (viewing pinned chunks in a project) but does not explicitly state when to use this tool versus alternatives like memory_lookup or pin_memory. No 'when not to use' guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_lookupA
在 AIOS 知识库中主动检索相关记忆（推理中断 / demand paging）。

当你推理时发现需要某类知识但不确定时，调用此工具：
- 上次关于某模块的决策
- 某功能的已知设计约束
- 某段代码的参数格式
- 之前总结的性能数据

Args:
    query: 查询字符串（自然语言或关键词均可）
    top_k: 返回结果数量（默认 5）
    chunk_types: 可选，过滤 chunk 类型（如 ["design_constraint", "decision"]）
    project: 可选，指定项目 ID（默认自动推断）

Returns:
    格式化的检索结果，包含 summary 和 content 摘要
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_kNo
chunk_typesNo
projectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It describes the tool as an active retrieval operation with 'reasoning interruption / demand paging' context, implying a read-only action. However, it does not mention any side effects, permission requirements, or rate limits. The description is adequate but could be more detailed about behavioral traits such as whether results are cached or if there are size limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a one-line introduction, a bulleted list of usage examples, and clearly labeled Args/Returns sections. Every sentence adds value. It is concise without being overly brief; the examples make it practical. Minor redundancy: the examples could be more concise, but overall it is well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has an output schema (not shown but noted), the description does not need to detail return values, though it provides a brief summary. It covers the essential context: when to use, what parameters to provide, and example queries. The description is complete enough for an AI agent to understand the tool's role and usage, though it could mention that it is a read-only operation explicitly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the tool description must compensate. It explains each parameter: query (natural language or keywords), top_k (default 5), chunk_types (optional filter with examples), and project (optional, auto-inferred). This adds significant meaning beyond the schema, which only provides names and types. The examples for chunk_types are particularly helpful. A small improvement would be to clarify the format of the query string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: active retrieval of relevant memories from the AIOS knowledge base. It provides concrete examples of queries (e.g., decisions, design constraints, performance data), making the specific resource and action unambiguous. The function is well-distinguished from siblings (list_pinned, memory_stats, pin_memory, unpin_memory) which handle different memory operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use the tool: 'when you need knowledge but are unsure' during reasoning. It gives example scenarios that guide appropriate usage. However, it lacks explicit guidance on when NOT to use it or alternatives, though siblings are distinct. A clear context is provided, but no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_statsB
查询 AIOS 知识库的统计信息（chunk 数量、类型分布、近期活跃度）。

Returns:
    知识库统计摘要
ParametersJSON Schema
NameRequiredDescriptionDefault
projectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only mentions it returns a summary. It does not disclose whether the operation is read-only, requires authentication, or has any side effects. For a tool with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences that are front-loaded with the action. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the output schema exists to describe return values, the description lacks details about the optional parameter and does not fully cover the tool's behavior. It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one optional parameter 'project' with 0% description coverage. The description does not explain the parameter's purpose or usage, failing to add meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies 'query AIOS knowledge base statistics' and lists specific metrics (chunk count, type distribution, recent activity). It clearly distinguishes from sibling tools like pin/unpin memory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives, but the purpose is clear. No exclusions or usage conditions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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:
    操作结果描述
ParametersJSON Schema
NameRequiredDescriptionDefault
chunk_idYes
pin_typeNosoft
projectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses all behavioral details: it prevents eviction by specific mechanisms (stale reclaim, DAMON DEAD, kswapd ZONE_MIN) and distinguishes hard (all) vs soft (except kswapd under extreme pressure). It also notes the return type.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections, OS analogy, and bullet points. It is informative but slightly long; however, every part adds value, so it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nuanced pinning behavior) and lack of annotations, the description covers purpose, usage, behavior, parameters, and return. It references related tools (memory_lookup) and includes an output schema, though the description already mentions a result description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully explains all 3 parameters: chunk_id (source from memory_lookup), pin_type (values and meaning), and project (default and auto-detection). This significantly adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool pins a chunk to prevent automatic eviction, with a helpful OS analogy (mlock). It distinguishes from siblings by focusing on pinning vs. listing, lookup, stats, and unpinning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when to use 'hard' vs 'soft' pinning with concrete examples (design constraints vs. important evidence) and mentions where to get the chunk_id (memory_lookup). It does not explicitly state when not to use it, but the trade-offs are implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unpin_memoryA
解除 chunk 在当前项目中的 pin，允许被自动淘汰。
OS 类比：munlock(addr, len) — 解除内存锁定，页面重新可被 swap out。

Args:
    chunk_id: 要解锁的 chunk ID
    project: 项目 ID（默认自动解析当前目录）

Returns:
    操作结果描述
ParametersJSON Schema
NameRequiredDescriptionDefault
chunk_idYes
projectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It lacks details on side effects, error conditions, idempotency, or prerequisites (e.g., what happens if the chunk is already unpinned). The OS analogy helps but is insufficient for complete transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a clear purpose sentence, an illustrative analogy, and a structured Args/Returns section. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema (not fully visible), the description covers basic usage but omits error handling and prerequisites. It is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context beyond the schema: it explains chunk_id as 'chunk ID to unlock' and project as 'project ID (default auto-resolves current directory)'. Schema coverage is 0%, so the description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to unpin a chunk in the current project, using an OS analogy (munlock) that reinforces the concept. It distinguishes itself from sibling tools like pin_memory by indicating it is the inverse operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as the inverse of pin_memory, but does not explicitly state when to use it over alternatives or provide exclusions. The context of sibling tools is available but not referenced in the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedlist_pinned
    • First observedmemory_lookup
    • First observedmemory_stats
    • First observedpin_memory
    • First observedunpin_memory
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mnemos

    s60yucca
    A
    license
    B
    quality
    A
    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
    21
    MIT

  • Mnemo Cortex

    GuyMannDude
    A
    license
    Not graded
    quality
    A
    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.
    154
    MIT

  • umo-memory

    UmoLab
    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