Memento

Local-first persistent memory system for AI coding agents.

Memento gives Pi (and other coding agents) durable memory that survives session restarts. It captures, stores, and retrieves knowledge using a hybrid FTS5+grep search — no cloud, no dependencies, just local files.

Quick Start

git clone [email protected]:themuuln/memento.git ~/.agent-memory
pip3 install -e ~/.agent-memory
bash ~/.agent-memory/setup.sh

Restart Pi — you'll see memory recalled automatically when you ask questions.

Features

For Day-to-Day Use

| What | How | |---|---| | Auto-recall | When you ask a question, relevant memories are injected as context — no manual search needed | | Store memories | memory_remember LLM tool or remember this: ... in chat | | Search | memory_recall <query> tool or /memory-recall <query> slash command | | Status | memory_status tool or /memory-status slash command | | Session cleanup | Compaction messages captured automatically; learnings consolidated on quit |

For Power Users — CLI

memory status          # Health check + entry count
memory recall <query>  # Hybrid search (FTS5+grep via RRF)
memory ingest <text>   # Capture with pattern detection
memory doctor          # Diagnostics + --repair
memory inbox           # Pending compaction items
memory consolidate     # LLM-powered session analysis
memory forget <query>  # Remove entries
memory index --rebuild # Rebuild FTS5 index
memory sync push|pull  # Sync across devices

Multi-Device Sync

Sync your memory data across machines via git:

memory sync init        # One-time: creates private themuuln/memento-data repo
memory sync push        # Upload local memories to remote
memory sync pull        # Download and merge remote memories
memory sync status      # Check sync state

Uses a separate private GitHub repo (themuuln/memento-data) that stores only your global/memories.md and graph/memory-graph.jsonl. Each machine pushes/pulls independently — merge conflicts are resolved by keeping the latest version.

Requires gh auth on each machine (gh auth login).

Under the Hood

~/.agent-memory/
├── memory                   # CLI entry point
├── memory_cli/              # Python package (26 files, 7 commands)
│   ├── cli.py               # Argparse CLI
│   ├── adapters/             # Flat file, graph, search backends
│   ├── commands/             # ingest, recall, consolidate, forget, etc.
│   └── core/                 # parser, dedup, hybrid search, FTS5 index
├── extensions/               # Pi TypeScript extensions
│   ├── memory-tools.ts              # 3 LLM tools, 4 slash commands, auto-recall, shutdown hook
│   └── memory-compaction-capture.ts  # Captures messages before compaction
├── global/memories.md        # Source of truth (durable markdown)
├── graph/memory-graph.jsonl  # Knowledge graph (MCP compatible)
├── config.json               # Triggers, patterns, LLM settings
├── tests/                    # 105 pytest tests
├── setup.sh                  # One-command installer
└── INSTALL.md                # Full installation guide

Search Architecture

Hybrid retriever combining:

• FTS5 — SQLite full-text search with Porter stemming
• Grep — Line-by-line regex fallback
• RRF ranking — Reciprocal Rank Fusion merges both results
• OR fallback — If AND query returns 0 results, auto-retry with OR
• Alias expansion — nextjs→next.js, tailwind→tailwindcss, etc.

Storage

Dual-write to flat markdown + MCP knowledge graph JSONL. FTS5 index is auto-rebuilt after every write.

CLI Commands

| Command | Description | |---|---| | status | Health check, entry count, section breakdown | | ingest | Capture memory from stdin/file with trigger detection | | recall | Search memories (hybrid by default, --no-hybrid for grep-only) | | forget | Remove entries (--apply to confirm) | | index | Rebuild FTS5 search index | | inbox | Show/process pending compaction items | | consolidate | LLM-powered session transcript analysis | | parse | Parse and validate memories.md | | doctor | Deep diagnostics with --repair |

Environment

| Variable | Default | Purpose | |---|---|---| | AGENT_MEMORY_DIR | ~/.agent-memory | Root directory | | MEMORY_CLI | memory | CLI binary override | | OPENCODE_GO_API_KEY | (required) | For LLM consolidation via pi --print |

License

MIT