# mvm

**Repository Path**: sk-wang-sh/mvm

## Basic Information

- **Project Name**: mvm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MVM — Minimum Viable Memory

**A seven-layer reference implementation of the Agent Memory Stack for AI agents.**

> Companion code for the paper: *"Auditing Retrieval Claims in LLM Agent Memory"* (Wang, Li & Feng, 2026).

## Architecture

```
┌──────────────────────────────────────────────┐
│          AI Agent                             │
├──────────────────────────────────────────────┤
│ Layer 1: Event Log         (append-only)     │
│ Layer 2: Structured Memory (namespaced)      │
│ Layer 3: Tiered Summary    (L0/L1/L2)        │
│ Layer 4: Consolidation     (Dream/promote)   │
│ Layer 5: Session Recall    (FTS5 x-session)  │
│ Layer 6: Retrieval         (ChromaDB / RAG)  │
│ Layer 7: Governance        (TTL/decay)       │
└──────────────────────────────────────────────┘
```

| Layer | Purpose | Implementation |
|-------|---------|---------------|
| **1. Event Log** | Append-only conversation history | JSONL file |
| **2. Structured Memory** | Namespaced: profile/project/session/policy/kb | Partitioned JSONL |
| **3. Tiered Summary** | L0 (~50 tok) / L1 (~500 tok) / L2 (full) | tiktoken or LLM-generated |
| **4. Consolidation** | Background promotion of candidates to long-term memory | Dream / Auto-Dream pattern |
| **5. Session Recall** | Cross-session lexical search over conversation history | SQLite FTS5 |
| **6. Retrieval** | Semantic search fallback | ChromaDB |
| **7. Governance** | TTL, confidence, correction, decay | Metadata + expiration |

## Install

```bash
pip install chromadb tiktoken
pip install -e .

# Optional: to run Experiment 3 (AAAK compression via the official
# MemPalace Dialect API), install the mempalace extras:
pip install -e ".[experiments]"
# or: pip install mempalace>=3.1.0
```

Experiments 4–6 additionally require an API key for LLM or embedding calls:

```bash
export AIHUBMIX_KEY="sk-..."        # for exp4, exp5, exp6_* sensitivity runs
export DASHSCOPE_API_KEY="sk-..."   # alternative for exp5/exp6 via DashScope
```

Without the above, `experiments/run_all.py` skips the affected experiments with a warning rather than failing.

## LLM-Powered Summaries (Optional)

By default, Layer 3 uses tiktoken truncation for L0/L1 summaries. To enable real LLM-generated summaries, set an API key for any OpenAI-compatible endpoint:

```bash
# Alibaba DashScope (Qwen)
export MVM_API_KEY="sk-your-dashscope-key"
export MVM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export MVM_MODEL="qwen-plus"

# OpenAI
export MVM_API_KEY="sk-your-openai-key"
export MVM_BASE_URL="https://api.openai.com/v1"
export MVM_MODEL="gpt-4o-mini"

# Any OpenAI-compatible endpoint works
```

Without an API key, everything still works — summaries just use truncation instead of generation.

## Quickstart

```python
from mvm import MVM

m = MVM(path="./my_agent_memory")

# Layer 1: Log raw events
m.log("user", "Our order system P99 is over 2 seconds")

# Layer 2: Store structured memories
m.remember("project", "Order table slow queries on time range", confidence=0.85)
m.remember("policy", "SLA 99.99%, zero downtime required", confidence=1.0)

# Layer 3: Get tiered summaries
summary = m.summarize("project")
print(summary["l0"])  # ~50 tokens
print(summary["l1"])  # ~500 tokens

# Layer 4: Consolidation (promote recent candidates)
promoted = m.dream(namespace="consolidated")

# Layer 5: Cross-session recall
hits = m.search_sessions("database performance", limit=3)

# Layer 6: Semantic retrieval
results = m.search("database performance", top_k=3)

# Layer 7: Governance
m.decay()                                    # Remove expired memories
m.correct("project", memory_id, "P99 now 200ms")  # Fix a memory
print(m.stats())                             # Operational metrics
```

## Run Example

```bash
python examples/quickstart.py
```

## Run Tests

```bash
pip install pytest
python -m pytest tests/ -v
```

## Design Principles

Based on the engineering heuristics from the paper (Appendix B):

1. **Never write long-term memory from a single utterance** — require repeated occurrence, user confirmation, or demonstrated task benefit
2. **Always separate raw records from summaries** — Layer 1 (immutable) vs Layer 3 (disposable cache)
3. **Namespace profiles separately from knowledge** — Layer 2 enforces profile/project/session/policy/kb separation
4. **Instrument your memory system** — `m.stats()` tracks token counts, memory counts, expiration rates
5. **Benchmark on your own data** — L0/L1/L2 token budgets are configurable; tuned FTS5 may beat off-the-shelf embeddings on your corpus

## Citation

```bibtex
@article{wang2026auditing,
  title={Auditing Retrieval Claims in LLM Agent Memory},
  author={Wang, Hao and Li, Hongliang and Feng, Junhui},
  year={2026}
}
```

## License

MIT