Memento Vault

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.

Related MCP server: bikky

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

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.

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