# 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

```bash
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

```bash
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`:

```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**

```json
{
  "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**

```json
[
  {
    "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**

```json
[
  {
    "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.

```json
[
  { "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.

```bash
npm run admin
```

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

```bash
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`**

```bash
#!/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`**

```bash
#!/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
```

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

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

```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:

```json
{
  "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](docs/ARCHITECTURE.md): Design principles, storage model, search algorithm, context engineering
- [Schema Reference](docs/SCHEMA.md): Full field reference, dedup rules, response formats
- [Context Engineering Guide](docs/CONTEXT_ENGINEERING.md): Progressive disclosure strategy, writing guidelines, anti-patterns, scaling

---

## License

MIT