Memento

Persistent, searchable memory for AI assistants.

Memento is an MCP server that gives Claude long-term memory across sessions, projects, and machines. Store what you learn, search it later, recall only what you need.

No databases. No embedding models. No external services. Plain files, runs locally.

---

How it works

Most AI assistants forget everything the moment a session ends. Memento fixes that by giving Claude a persistent store it can read and write to across sessions.

The design is built around two-phase retrieval: search returns compact snippets so the AI can decide what's relevant, then recall fetches full content only for the entries it actually needs. This keeps context windows lean and costs low.

Storage is append-only JSONL files on disk. Search is BM25, the same probabilistic ranking that powers most search engines. No ML, no APIs, just fast deterministic text matching.

---

Installation

Option 1: Claude Code plugin

claude plugin add github:Kotrotsos/memento-core

The plugin auto-builds on first use via a SessionStart hook (takes about 10 seconds). After that it's instant.

Option 2: Manual

git clone https://github.com/Kotrotsos/memento-core.git
cd memento-core
npm install && npm run build

Then register the MCP server. Add this to your ~/.mcp.json or a project-level .mcp.json:

{
  "mcpServers": {
    "memento": {
      "command": "node",
      "args": ["/path/to/memento-core/build/index.js"]
    }
  }
}

Restart Claude Code. You should see the memory_* tools available.

---

MCP Tools

Memento exposes five tools over the Model Context Protocol.

memory_store

Create a new memory or update an existing one.

memory_store(content, namespace?, tags?, id?, relations?, ttl?)

Parameter	Type	Default	Description
content	string	required	The memory text
namespace	string	"global"	Where to file it: global, projects/my-app, decisions, etc.
tags	string[]	[]	Labels for filtering: architecture, preference, bug, etc.
id	string	auto	Provide an existing ID to update that memory
relations	string[]	[]	IDs of related memories
ttl	string	permanent	ISO 8601 expiry. After this timestamp, the memory is excluded from results

Example

{
  "content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append).",
  "namespace": "decisions",
  "tags": ["architecture", "storage"]
}

---

memory_search

Search memories with BM25 ranking. Returns snippets, not full content.

memory_search(query, namespace?, tags?, limit?)

Parameter	Type	Default	Description
query	string	required	Search terms
namespace	string	all	Scope results to a namespace
tags	string[]	—	Filter by tags (AND logic, all must match)
limit	number	10	Max results to return

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "namespace": "decisions",
    "tags": ["architecture", "storage"],
    "snippet": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files...",
    "score": 6.41,
    "updated": "2026-02-26T14:30:00Z"
  }
]

Snippets are the first ~150 characters of content, enough to judge relevance without burning context.

---

memory_recall

Fetch full content for specific memory IDs. Use after search to load what you actually need.

memory_recall(ids)

Parameter	Type	Description
ids	string[]	One or more memory IDs from a previous search

Response

[
  {
    "id": "550e8400-...",
    "namespace": "decisions",
    "content": "Use JSONL for storage. Chosen over SQLite (binary, overkill) and single JSON files (can't stream/append). JSONL is append-friendly, streamable, human-readable, and grep-compatible.",
    "tags": ["architecture", "storage"],
    "created": "2026-02-26T14:30:00Z",
    "updated": "2026-02-26T14:30:00Z",
    "source": "claude-code",
    "relations": [],
    "ttl": null
  }
]

---

memory_delete

Soft-delete a memory. The entry stays in the JSONL file but is excluded from all queries.

memory_delete(id, namespace)

---

memory_list_namespaces

List all namespaces with entry counts. No parameters.

[
  { "namespace": "global", "count": 42 },
  { "namespace": "projects/my-app", "count": 17 },
  { "namespace": "decisions", "count": 8 }
]

---

Admin UI

Memento includes a web interface for browsing and managing memories.

npm run admin

Opens at http://localhost:3000. Custom port:

MEMENTO_ADMIN_PORT=8080 npm run admin

What you get:

• Dashboard with memory count, namespace count, tag cloud, and recent entries
• Namespace browser with drill-down
• Full memory viewer with metadata (tags, timestamps, source, TTL, relations)
• Create, edit, and delete via forms
• BM25 search with namespace and tag filters
• Server info page with storage path and disk usage

---

Making Claude use Memento automatically

Memento works best when Claude recalls context at the start of a session and stores important things before finishing. You can enforce this with Claude Code hooks.

1. Create the hook scripts

~/.claude/hooks/session-start-memento.sh

#!/bin/bash
INPUT=$(cat)
PROJECT=$(basename "$(echo "$INPUT" | jq -r '.cwd // empty')" 2>/dev/null)
if [ -n "$PROJECT" ]; then
  echo "[Memento] Search Memento for relevant memories about \"$PROJECT\" before starting work."
else
  echo "[Memento] Search Memento for relevant memories before starting work."
fi

~/.claude/hooks/stop-memento.sh

#!/bin/bash
STOP_REASON=$(cat | jq -r '.stop_reason // "end_turn"')
if [ "$STOP_REASON" = "end_turn" ]; then
  echo "[Memento] Before finishing: did you store significant findings, decisions, or completed work in Memento?"
fi

chmod +x ~/.claude/hooks/session-start-memento.sh
chmod +x ~/.claude/hooks/stop-memento.sh

2. Register the hooks in ~/.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/session-start-memento.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/stop-memento.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. Auto-allow Memento tools

Add these to permissions.allow so Claude never has to ask for permission:

{
  "permissions": {
    "allow": [
      "mcp__memento__memory_store",
      "mcp__memento__memory_recall",
      "mcp__memento__memory_search",
      "mcp__memento__memory_delete",
      "mcp__memento__memory_list_namespaces"
    ]
  }
}

---

Writing good memories

The quality of what you get back depends on the quality of what you store.

Front-load the key information. BM25 doesn't care about position, but snippets show the first 150 characters. Put the core fact first.

# Good
Use JSONL for storage. Chosen over SQLite (binary) and single JSON files (can't stream).

# Bad
After a long discussion about storage options, we eventually decided that JSONL would work best.

One concept per memory. Separate concerns don't compete for relevance and can be independently recalled.

Always include tags. Memories without tags can only be found by full-text search across everything.

Use namespaces to segment domains. A single global namespace with thousands of entries gets noisy. Scope to projects/my-app or decisions for cleaner results.

---

Storage layout

~/.memento/
  memories/
    global.jsonl
    decisions.jsonl
    procedures.jsonl
    projects/
      my-app.jsonl
      another-project.jsonl

Each line in a .jsonl file is one memory entry. Writes are always appends. Updates write a new entry with the same ID, and the loader keeps only the latest version. Deletes write an entry with deleted: true.

Set MEMENTO_HOME to change the base directory.

---

Configuration

Variable	Default	Description
MEMENTO_HOME	~/.memento	Base directory for all storage
MEMENTO_ADMIN_PORT	3000	Port for the admin web UI

---

Plugin commands

When installed as a Claude Code plugin, three slash commands are available:

Command	Description
/memento-search <query>	Search memories and optionally recall full content
/memento-store <content>	Store a memory with guided namespace and tag selection
/memento-admin [port]	Start the admin web UI

---

Technical details

• Architecture: Design principles, storage model, search algorithm, context engineering
• Schema Reference: Full field reference, dedup rules, response formats
• Context Engineering Guide: Progressive disclosure strategy, writing guidelines, anti-patterns, scaling

---

License

MIT