# Memento Vault

[![CI](https://github.com/sandsower/memento-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/sandsower/memento-vault/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A zettelkasten your coding agents write.
Plain markdown, git-backed, injected back into every session.

Every session starts from zero: agents forget everything between sessions.

## What a note looks like

Every durable note carries epistemic metadata: how confident is this, and under what conditions would it stop being true?
This is trimmed from the worked example in [docs/frontmatter-schema.md](docs/frontmatter-schema.md#example) (full version there has `project_path` and `session_id` too):

```yaml
---
title: Redis cache invalidation requires explicit TTL
type: discovery
tags: [redis, caching, backend]
source: session
origin: claude_triage:claude
certainty: 4
validity-context: while using Redis 7.x with cluster mode
project: my-api
branch: feat/cache-layer
date: 2026-03-15T14:30
---

Redis cluster mode does not propagate `DEL` commands across shards for keys
with no TTL set. Every cached key needs an explicit TTL even if you plan to
invalidate it manually, otherwise stale reads happen on replica shards.
```

<!-- TODO(vic): screenshot -- Obsidian graph view of a real vault -->
<!-- TODO(vic): GIF -- live [vault] injection appearing mid-session in Claude Code -->

## Why

- Notes are plain markdown with epistemic frontmatter (certainty, validity-context, supersession), not opaque vectors in someone else's database.
- Retrieval is automatic: session-start briefing, prompt recall, and read-tool context inject relevant notes without you asking.
- Filtered search and graph queries (`memento_related`) sit on top of ranked retrieval, so you can combine "find this" with "only certainty >= 4" or "walk what links to this."
- Durability tiers decouple decay-immunity from certainty: pinned and recently-resurfaced notes persist, cold notes decay and can be auto-archived.
- Works the same way from Claude Code hooks, any MCP-compatible agent, or a remote vault shared across devices.
- It's a git repo. Read it, diff it, grep it, back it up, no vendor lock-in.

## Quickstart

```bash
brew tap sandsower/tap
brew install memento-vault
memento-vault install
```

Start a Claude Code session in any git repo and watch for `[vault]` lines in the transcript.
Here is a real session-start briefing line, generated by running `build_briefing()` against this repo's own 19-note eval fixture vault (`evals/golden/fixtures/vault`):

```
[vault] Project: memento-vault | 0 sessions | 19 notes
```

That's the whole loop: work normally, and relevant notes surface before you ask for them.
Full install flags (Homebrew, git/manual, `--experimental`, `--mcp`, `--remote`, health checks, upgrading) live in [docs/install.md](docs/install.md).

## How it works

A session ends, the triage hook reads the transcript and decides what's worth keeping: short sessions get a one-line fleeting entry, substantial sessions with new insight spawn a background agent that writes atomic notes with epistemic frontmatter and wikilinks.
Tenet, the retrieval side, injects relevant notes back at session start, before each prompt, and when the agent reads a file it has notes about, all silently when there's nothing relevant to say.
Inception periodically clusters those notes by embedding similarity and synthesizes higher-order pattern notes that span sessions.
Full lifecycle, hook internals, and Inception's research grounding: [docs/how-it-works.md](docs/how-it-works.md).

## Pick your integration

| | Claude Code hooks | MCP agents (Cursor, Codex, Windsurf, OpenCode) | Remote vault |
|---|---|---|---|
| Install | `./install.sh` | `./install.sh --mcp` | `./install.sh --remote <url>` |
| Capture | Automatic SessionEnd hook | `memento_capture` tool call | Same, synced over HTTP |
| Retrieval | Automatic session/prompt/read-tool injection | Explicit `memento_search` / `memento_recall` tool calls | Same tools, remote-backed |
| Docs | [docs/how-it-works.md](docs/how-it-works.md) | [docs/mcp.md](docs/mcp.md) | [docs/remote-deployment.md](docs/remote-deployment.md) |

## Features

### Filtered search and graph lookups

`memento_search` takes optional typed filters (type, tags, certainty range, dates, branch, project) on top of ranked retrieval, and `memento_related` walks the wikilink graph around a note with pure topology, no scoring.
Example: `memento_search({"query": "cache invalidation", "certainty_min": 4})` finds only notes you've marked reliable; `memento_related({"note": "redis-cache-ttl"})` shows what links to it.
Full tool inventory and connection instructions: [docs/mcp.md](docs/mcp.md).

### MCP tool inventory

<!-- memento-mcp-tools:start -->
The MCP server currently registers **20 tools**. This table is generated from `memento.mcp_inventory.MCP_TOOL_INVENTORY`; refresh/check it with `memento-vault tools --markdown` or `memento-vault tools --check`.

| Tool | Category | What it does | When to use it |
|------|----------|--------------|----------------|
| `memento_search` | Read | Search vault notes with BM25, optional semantic search, hybrid ranking, temporal decay, PageRank/access-log boosts, `concrete: auto\|true\|false` for exact identifiers and quoted phrases, and optional typed post-filters (type, tags, certainty, dates, branch, session_id, project) that mirror `memento_query`'s filter semantics. | Use before answering questions about past decisions, prior fixes, project history, session context, recurring patterns, or exact identifiers, including when ranked retrieval also needs metadata constraints. Do not use it to read a known note path. |
| `memento_query` | Read | Run typed metadata filters, counts, date buckets, and recent-session listings over note frontmatter without reading full note bodies. | Use for count/list/filter questions by project, type, tag, certainty, source, date, branch, or session_id; use `memento_search` instead for topical recall or semantic retrieval. |
| `memento_contradictions` | Read | Inspect a topic for deterministic validity chains (note -> invalidated_by -> ... with dates) built from `valid_from`/`invalidated_by` frontmatter; the pre-MEM-163 lexical polarity-guessing report is available behind `contradictions_lexical_fallback` config. | Use when comparing competing notes about the same topic, checking whether a note has been explicitly invalidated, or walking a note's full validity history alongside certainty/date context. |
| `memento_related` | Read | Walk the wikilink graph around a note: outbound/inbound links, a depth-limited neighborhood, and its supersession chain. Pure topology, no relevance scoring. | Use for "what links to X", neighborhood expansion, or finding the current/superseded version of a note; use `memento_search` instead for topical/semantic retrieval. |
| `memento_briefing` | Lifecycle | Build a compact session-start briefing payload for host adapters. | Host-adapter primitive for automatic injection; not a general user-answering tool. |
| `memento_recall` | Lifecycle | Build prompt-time recall context for host adapters. | Host-adapter primitive for automatic injection before an agent turn; not a general user-answering tool. |
| `memento_tool_context` | Lifecycle | Build read-tool context for a concrete file path. | Host-adapter primitive for automatic read-tool injection; not for explicit recall/search requests. |
| `memento_session_context` | Lifecycle | Build a one-call budgeted session context packet that can include status, recent context, recall, and tool-context preview metadata. | Host-adapter primitive that replaces separate briefing/recall/status calls when a host wants one compact payload. |
| `memento_get` | Read | Read full note content by name or path. | Use after `memento_search` when a returned path needs full content, or directly when the user already supplied an exact note path/name. |
| `memento_status` | Operational | Report vault health/status, note counts, project counts, and safe config summary. | Use for operational checks and setup debugging; not for recall, project history, or note content. |
| `memento_list` | Sync | List notes with optional content hashes for lightweight inventory/sync. | Use for sync/inventory clients; not for topical recall or reading notes. |
| `memento_store` | Write | Write a single knowledge note with managed frontmatter and project indexing. | Low-level write primitive for sync/automation or agents without skill support; interactive Claude/Codex sessions should prefer `/memento` or local hooks. |
| `memento_replace_note` | Sync | Replace an existing note at a known path for explicit conflict resolution. | Use only after a sync client has identified the exact remote path to resolve; it is not a general note creation primitive. |
| `memento_store_smart` | Write | Search for close matches before writing, and return duplicate/update/supersede suggestions. | Use when you want a write decision with candidate paths/reasons before creating a note; it avoids obvious duplicates by default. |
| `memento_daily_snapshot` | Write | Write a deterministic `notes/daily-<date>-<repo-slug>.md` snapshot with an append-only supersede chain. | Low-level structured daily-snapshot primitive for path-controlled integrations; do not use for ordinary notes, interactive memory capture, or session triage. |
| `memento_capture` | Write | End-of-session triage from a transcript path or structured summary; writes fleeting session state and optionally an atomic note. | Low-level SessionEnd equivalent for agents without hook support; not a replacement for interactive `/memento` workflows. |
| `memento_capture_run_lesson` | Write | Queue or explicitly write one typed automated-run lesson candidate with provenance refs. | Use for Rondo/Beislið-style post-run learning; queues by default and rejects raw logs, transcripts, run ledgers, proofs, and patch blobs. |
| `memento_synthesize_failures` | Write | Dry-run batch synthesis from sanitized external run summaries, with optional approved lesson-note writes. | Use for Rondo/Beislið-style batch failure learning; rejects raw logs/run stores and never executes advisory issue/gate/docs actions. |
| `memento_preserve` | Write | Archive a file or directory bundle under `archive/<slug>/` with a manifest, a lightweight index note, and optional project-linking. | Use for evidence packets, screenshots, handoff bundles, or other artifacts that should stay intact; copy by default, move only when explicitly requested. Do not use it for ordinary knowledge capture or atomic notes. |
| `memento_reindex` | Maintenance | Rebuild the search index from all markdown files after out-of-band changes. | Use after bulk adds, git pull, Obsidian sync, or stale-index evidence; not as the default response to a broad/empty search miss. |
<!-- memento-mcp-tools:end -->

### Durability tiers and auto-archive

Decay-immunity is driven by a durability tier (`pinned` / `hot` / `warm` / `cold`), not certainty: a certainty-5 note that's never been resurfaced decays like a certainty-1 note.
An opt-in sweep (`archive_sweep_enabled`) reversibly archives cold notes past an age threshold, never a hard delete.
Details and the exact tier rules: [docs/frontmatter-schema.md#durability-tier](docs/frontmatter-schema.md#durability-tier).

### Fleeting note lifecycle

An opt-in sweep (`fleeting_lifecycle_enabled`) promotes fleeting session logs to permanent notes once they're resurfaced or cited, and reversibly archives the rest past an age threshold.
Configuration and promotion rules: [docs/configuration.md#fleeting-note-lifecycle-mem-153](docs/configuration.md#fleeting-note-lifecycle-mem-153).

### Inception (pattern synthesis)

Inception clusters vault notes by embedding similarity and synthesizes pattern notes that surface insights no single session would catch on its own.
Opt in with `inception_enabled: true`, preview with `/inception --dry-run`; requires QMD and `pip install numpy hdbscan scikit-learn`.
Architecture, cost, and limitations: [docs/how-it-works.md#inception-background-consolidation](docs/how-it-works.md#inception-background-consolidation).

### Pi extension

A native TypeScript extension for the pi coding agent, with a TUI dashboard (`/memento`), automatic SessionEnd-style capture, and manual queue review for explicit captures.
Try it with `pi -e ./extensions/memento.ts`.
Commands, config, and env vars: [docs/pi.md](docs/pi.md).

### Skills

`/memento` captures insights mid-session, `/inception` finds cross-session patterns, `/memento-defrag` archives stale notes, `/preserve` archives artifact bundles intact, `/start-fresh` and `/continue-work` handle context handoffs.
Full skill list and the concierge search agent: [docs/how-it-works.md#the-skills](docs/how-it-works.md#the-skills).

### Obsidian (optional)

Open `~/memento` as an Obsidian vault for graph view, Base views (by type, project, recent), and wikilink navigation.
The installer wires this up automatically: [docs/install.md](docs/install.md).

## Why not just X?

**vs. mem0 / cloud memory services** -- those store your knowledge as embeddings in someone else's database, reachable only through their API.
Memento's notes are markdown files in your own git repo: readable, greppable, diffable, and portable without an export step.

**vs. claude-mem** -- claude-mem is Claude Code-only and stores memory as a SQLite/JSON blob.
Memento is agent-agnostic (Claude Code hooks, any MCP agent, pi) and the storage format is the same plain markdown you'd write by hand.

**vs. plain CLAUDE.md** -- CLAUDE.md is one file that grows without bound and has no retrieval; everything gets pasted into context whether it's relevant or not.
Memento is many small notes, retrieved by relevance to what you're doing right now, with epistemic metadata so stale conclusions can be identified instead of silently trusted.

**When NOT to use this** -- if you work in one short-lived repo and never revisit it, there's nothing to remember and Memento is pure overhead.
If your team already has a shared knowledge base with real editorial review, route durable decisions there and let Memento capture the session-local exhaust instead.
If you need multi-tenant access control or compliance-grade audit trails, look at a managed memory service; Memento's threat model is "one user, one vault."

## Docs

- [Install](docs/install.md), [Configuration](docs/configuration.md), [Search backends](docs/search-backends.md)
- [MCP](docs/mcp.md), [Pi extension](docs/pi.md), [OpenCode integration](docs/opencode-integration.md), [Remote deployment](docs/remote-deployment.md)
- [How it works](docs/how-it-works.md), [Architecture](docs/architecture.md), [Frontmatter schema](docs/frontmatter-schema.md), [Performance analysis](docs/performance-analysis.md)
- [Automation MemoryProvider contract](docs/automation-memory-provider.md)
- Full index: [docs/README.md](docs/README.md)

## Uninstall

```bash
cd memento-vault
./uninstall.sh
```

Removes hooks, skills, and the agent from `~/.claude/`.
Your vault and notes stay untouched.

## License

MIT