Memento Vault

CI License: MIT

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 (full version there has project_path and session_id too):

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

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

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.

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.

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

MCP tool inventory

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.

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.

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.

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.

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.

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.

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.

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, Configuration, Search backends
• MCP, Pi extension, OpenCode integration, Remote deployment
• How it works, Architecture, Frontmatter schema, Performance analysis
• Automation MemoryProvider contract
• Full index: docs/README.md

Uninstall

cd memento-vault
./uninstall.sh

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

License

MIT