记忆库

Requirements

• Python 3.9+
• Git
• Claude Code (for hook-based setup)
• QMD (optional, semantic search)
• Obsidian (optional, browsing)
• mcp Python package (for MCP setup, installed automatically by --mcp)

Install

Git/manual install

git clone https://github.com/sandsower/memento-vault.git
cd memento-vault
./install.sh

Creates the vault at ~/memento, copies hooks and the memento/ package into ~/.claude/, optionally sets up Obsidian views and QMD search. Works on Linux and macOS.

Custom vault path:

MEMENTO_VAULT_PATH=~/my-vault ./install.sh

The installer also links the memento-vault CLI into ~/.local/bin when possible, so future updates can use memento-vault update. If ~/.local/bin is not on your PATH, either add it or run the repository-local ./bin/memento-vault directly.

To safely rerun setup for the same version without discarding local edits:

memento-vault install --reinstall

Check local vault/install health at any time:

memento-vault health        # concise read-only diagnostics
memento-vault doctor        # alias for health
memento-vault health --json # structured output for automation

Warnings exit 0 by default; failures exit 1. Use --strict if automation should fail on warnings too. The command is read-only: it reports suggested repairs such as ./install.sh --reinstall, but does not modify vault/config files.

--force is reserved for recovery from broken installed files. It overwrites memento-managed files and requires confirmation, or MEMENTO_FORCE=1 in non-interactive environments.

Full install (hooks + retrieval + consolidation)

The base install captures knowledge. To also inject knowledge back into active sessions and enable background consolidation:

./install.sh --experimental

This adds two modules:

• Tenet -- three retrieval hooks that inject vault notes into active sessions (briefing, recall, tool context)
• Inception -- background consolidation that clusters notes and synthesizes cross-session patterns

Both require QMD. Inception also needs pip install numpy hdbscan scikit-learn. See Tenet and Inception for details.

MCP install (hookless agents)

For agents that support MCP but not native hooks (Cursor, Windsurf, etc.):

./install.sh --mcp

This installs the memento/ package, writes generic MCP server config, and registers the server with Claude Code and Codex when those CLIs are installed. The server runs over stdio via python -m memento. The installer verifies the mcp Python package is available and installs it if needed. Claude Code gets Claude-specific skills and the concierge agent under ~/.claude; Codex gets agent-agnostic skills under ~/.codex/skills.

You can combine flags: ./install.sh --experimental --mcp gives you hooks + retrieval + MCP.

Cloud deployment

Deploy the vault as a service accessible from multiple devices, agents, or the claude.ai/code web interface.

Docker Compose

The simplest option. Run on any machine with Docker — a home server, VPS, or your laptop.

MEMENTO_API_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") \
  docker compose up -d

Vault is at http://localhost:8745/mcp. For TLS on a VPS, add Caddy or use setup-remote.sh --host your-domain.com --tls.

Added to .zshrc/.bashrc by the installer (optional)

[ -x /path/to/memento-vault/bin/memento-vault ] && /path/to/memento-vault/bin/memento-vault warmup >/dev/null 2>&1

You can also run it manually:

Uninstall

cd memento-vault
./uninstall.sh

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

Configuration

Config lives at ~/.config/memento-vault/memento.yml. All options in docs/configuration.md.

```yaml vault_path: ~/memento exchange_threshold: 15 file_count_threshold: 3 qmd_collection: memento auto_commit: true

QMD (optional)

QMD adds semantic search over your vault. Without it the concierge agent uses the embedded backend or falls back to grep. QMD is required for Tenet and Inception.

qmd search "caching strategy" -c memento

The concierge agent uses QMD automatically when you ask about past decisions.

Obsidian (optional)

The installer copies Obsidian config and Base views into the vault. Open ~/memento as a vault and you get:

• Graph view showing how notes connect
• Base views: by type, by project, recent, decisions, bugfixes
• Daily notes pointed at fleeting/
• Wikilink navigation between notes

Pi extension

Memento ships a native pi extension from this repo. The extension is TypeScript, but lifecycle policy stays in Python core: pi calls a short-lived JSON adapter (python3 -m memento.pi_bridge) for briefing, recall, and read-tool context.

For local testing:

pi -e ./extensions/memento.ts

For package installation from a checkout:

pi install /path/to/memento-vault

The pi bridge does not start a long-lived MCP child process. Automatic durable writes are not enabled by default. Candidate captures are queued in local state for review and can be processed into curated notes manually.

Useful pi commands/tools:

• /memento — open the TUI dashboard for status, readable queued-capture review cards, explicit capture selection, processing previews, and live group-level processing progress.
• /memento-status or memento_status — bridge/vault status, lifecycle feature state, queue count.
• /memento-queue or memento_queue — list queued pi capture candidates with deterministic excerpts and size metadata.
• /memento-process or memento_process — process selected queued captures into curated durable notes. With no arguments the command shows a dry-run preview; use /memento for interactive selection and confirmation.
• memento_capture — manually write a durable note; pass queue: true to queue instead.

Pi bridge configuration can live in either ~/.config/memento-vault/pi-bridge.json, project-local .pi/settings.json, or project package.json. The bridge reads memento.piBridge first, then piBridge, then top-level keys:

{
  "memento": {
    "piBridge": {
      "enabled": true,
      "briefing": true,
      "promptRecall": true,
      "toolContext": false,
      "autoCapture": false,
      "captureQueue": true,
      "processQueue": true,
      "processQueueOnSessionClose": false,
      "processQueueMaxCaptures": 3,
      "processQueueModel": null,
      "maxInjectedChars": 4000,
      "maxToolContextPerSession": 5
    }
  }
}

Environment variables override file config:

When automatic capture is enabled, pi lifecycle events only create reviewable queue entries in local state (${MEMENTO_PI_STATE_HOME:-${XDG_STATE_HOME:-~/.local/state}/memento/pi}/queue/pi-captures.jsonl). They do not write durable notes until /memento-process or /memento curates the queue into one or more atomic Memento notes. Processing runs write progress under ${MEMENTO_PI_STATE_HOME:-${XDG_STATE_HOME:-~/.local/state}/memento/pi}/processing/<run-id>/, and the /memento footer shows a compact active/failed/interrupted indicator while background processing is visible. Shutdown capture is skipped if another lifecycle capture was already queued during the same session.

Before cutting a pi bridge release, run this interactive smoke checklist from a checkout:

pi -e ./extensions/memento.ts

Then verify /memento-status, /memento-queue, /reload, /new, /resume, /fork, /compact, and quit. The bridge uses short-lived python3 -m memento.pi_bridge calls rather than a persistent child process, so shutdown cleanup should leave no memento-owned child process behind.

Retrieval pipeline

prf_enabled: true # pseudo-relevance feedback query expansion rrf_enabled: true # reciprocal rank fusion (BM25 + vsearch) ppr_enabled: true # personalized pagerank link expansion reranker_enabled: true # cross-encoder reranking (local ONNX) multi_hop_enabled: false # follow wikilinks from top results ```

Extension points

Three ways to layer project-specific behavior on top without forking:

• project_rules in config: map directories to project slugs and ticket patterns
• extra_qmd_collections in config: search additional QMD collections alongside the vault
• ~/.claude/skills/memento-post/SKILL.md: post-capture hook that runs after /memento creates notes (e.g., promote to a team vault, apply domain tags)