> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Claude Code Session History into Agent Memory

> Bulk-import your existing Claude Code JSONL session transcripts so Agent Memory can recall context from sessions before you installed it.

If you've been using Claude Code before installing Agent Memory, you don't have to start with an empty memory. You can import your existing session history to immediately bootstrap your memory with past context — architectural decisions you've made, bugs you've debugged, patterns you've established, and code you've written.

## How It Works

Claude Code stores every session as a JSONL file in `~/.claude/projects/`. Each file is a newline-delimited transcript of the session: tool calls, file reads and writes, bash commands, user prompts, assistant responses, and task completions.

Agent Memory's import command reads these transcripts, parses each event, and processes them through the same pipeline as live sessions: deduplication, privacy filtering, synthetic compression, vector embedding, and BM25 indexing. After import, you can search this history with `memory_smart_search` exactly as you would search memories from current sessions.

## Import via CLI

Run the import from any terminal where `agentmemory` is installed:

```bash theme={null}
agentmemory import-jsonl
```

This auto-discovers all JSONL files under `~/.claude/projects/` and imports them. For large histories, use these options to control scope:

```bash theme={null}
# Limit to the 50 most recent files (fastest bootstrap)
agentmemory import-jsonl --max-files 50

# Import from a custom directory
agentmemory import-jsonl /path/to/my/exported/sessions
```

| Option          | Description                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--max-files N` | Import only the N most recent JSONL files. Defaults to `200` when omitted; maximum accepted value is `1000`. For histories larger than 1000 files, batch by project subdirectory. |
| `[path]`        | Specify a directory to import from instead of `~/.claude/projects/`.                                                                                                              |

<Tip>
  Start with `--max-files 50` for a quick bootstrap covering your most recent work. Agent Memory will continue building naturally from future live sessions, so you don't need to import everything at once.
</Tip>

## Import via API

You can also trigger an import over the REST API, which is useful for scripting or automation:

```bash theme={null}
curl -X POST http://localhost:3111/agentmemory/replay/import-jsonl \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/.claude/projects/my-project",
    "maxFiles": 20
  }'
```

If you have `AGENTMEMORY_SECRET` set, include the `Authorization` header:

```bash theme={null}
curl -X POST http://localhost:3111/agentmemory/replay/import-jsonl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-here" \
  -d '{"path": "/home/user/.claude/projects", "maxFiles": 50}'
```

## What Gets Imported

| Content type          | Imported                                   |
| --------------------- | ------------------------------------------ |
| File reads and writes | ✅ Captured as observations with file paths |
| Bash command runs     | ✅ Captured with commands and outputs       |
| Web search tool calls | ✅ Captured with queries and results        |
| User prompts          | ✅ Privacy-filtered before indexing         |
| Assistant responses   | ✅ Processed for key facts and decisions    |
| Task completions      | ✅ Recorded as session summaries            |

Agent Memory applies the same privacy filter used for live sessions: API keys, secrets, tokens, and content tagged `<private>` are stripped before any data is stored or indexed.

## After Import

Once the import finishes, verify the results:

```bash theme={null}
agentmemory status
```

This shows total session counts, memory counts, and a breakdown of imported vs. live sessions.

To confirm that recall is working, run a semantic search against something you discussed in a past session:

```bash theme={null}
agentmemory demo
```

Or use the `memory_smart_search` MCP tool from inside your agent — search for a technology, file, or decision you know appeared in a previous session and confirm the agent can find it.

You can also browse imported sessions in the real-time viewer at `http://localhost:3113`. Imported sessions appear in the Replay tab alongside live sessions, with full timeline scrubbing and event playback.

<Note>
  Large import sets may take several minutes to process, especially if `CONSOLIDATION_ENABLED=true` is set. Consolidation runs at the end of each imported session and involves LLM calls for summarization and graph extraction. For a faster initial import, you can temporarily set `CONSOLIDATION_ENABLED=false`, then run `agentmemory consolidate` manually after the import completes.
</Note>

## Keeping History Fresh

Claude Code's `cleanupPeriodDays` setting (in `~/.claude/settings.json`, default **30 days**) automatically deletes JSONL transcripts older than that window. If you install Agent Memory on a months-old Claude Code setup, transcripts from before the cleanup window are already gone.

To prevent future data loss:

* **Raise the cleanup window** in `~/.claude/settings.json`: `"cleanupPeriodDays": 90`
* **Or use live capture** (recommended): once the Agent Memory hooks are wired via `agentmemory connect claude-code`, every session turn lands in Agent Memory in real time — Claude Code's JSONL cleanup becomes irrelevant.