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

# Import Coding-Agent Sessions

> Give Claude Code and Codex one shared memory of every session they already ran

Each agent only sees its own past sessions. After the import, one question covers what Claude Code did last month and what Codex did yesterday.

## What You'll Build

Claude Code and Codex save every session on your machine, in `~/.claude/projects` and `~/.codex/sessions`. The cookbook reads that history: each prompt you typed and the agent's final answer to it. cognee remembers it all in one dataset, with each agent's sessions tagged separately. Then it answers your question over every agent's history together, and over each agent's history alone.

Building the memory takes one `cognee.remember` call per agent, and every answer is one `cognee.recall` call.

The complete cookbook is
[`examples/cookbooks/import_agent_sessions/`](https://github.com/topoteretes/cognee/tree/dev/examples/cookbooks/import_agent_sessions).

## Try It on Sample Data

The sample is four sessions from two weeks of work on a made-up web shop, `acme-shop`. Claude Code added an order history page and fixed double charges on checkout retries. Codex fixed a checkout bug that let two orders buy the last item in stock, and added rate limiting to the public API. You need only an [LLM key](/setup-configuration/llm-providers), not any history of your own.

```bash theme={null}
git clone https://github.com/topoteretes/cognee.git && cd cognee
uv sync
echo 'LLM_API_KEY="your-key"' >> .env
```

`LLM_API_KEY` alone is enough for OpenAI, cognee's default LLM provider. Other providers, such as Anthropic, Gemini, Azure OpenAI, AWS Bedrock or a local model through Ollama, need a few more lines in the same `.env`: [LLM Providers](/setup-configuration/llm-providers#provider-setup-guides) lists them for each provider. Embeddings need no key: the cookbook always embeds locally with [fastembed](/setup-configuration/embedding-providers) (`BAAI/bge-small-en-v1.5`, downloaded once, about 70 MB), whichever LLM key you use. If you set `EMBEDDING_PROVIDER` in `.env` instead, keep it for every run, because all vectors in a dataset must come from one model.

**Terminal**

```bash theme={null}
uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py
```

**Coding agent**

The cognee repo ships a skill for this cookbook, [`.agents/skills/multiagent-memory-setup/SKILL.md`](https://github.com/topoteretes/cognee/blob/dev/.agents/skills/multiagent-memory-setup/SKILL.md). Claude Code and Codex find it on their own when you open them in the cognee folder. Ask in plain words, or type `/multiagent-memory-setup` in Claude Code:

```text theme={null}
Import my earlier Claude Code and Codex sessions into cognee, but show me the demo on sample sessions first.
```

It runs the demo and tells you the answers come from sample data. Ask it to import your own history and it runs `--check` first, tells you which agents and sessions it found, and asks which agents and which projects to import. It never chooses for you.

```text theme={null}
[setup] Demo: sample Claude Code and Codex sessions; cognee runs on openai (LLM_API_KEY), local fastembed embeddings.
[setup] Wrote the sample Claude Code and Codex sessions from setup.py.
[clear] Forgot the dataset imported_agent_sessions_demo
[read_sessions] Claude Code: 2 sessions, 4 turns
[read_sessions] Codex: 2 sessions, 2 turns
[ingest_sessions] Remembered 2 claude sessions as imported_agent_sessions_demo:claude_code
[ingest_sessions] Remembered 2 codex sessions as imported_agent_sessions_demo:codex
[ask] you> What did I work on in these sessions?
[ask] all sessions> Your sessions cover the acme-shop project, an online store. The work includes an order history page under /account/orders with a new orders(user_id, created_at) index (migration 0042), a fix for stock overselling at checkout (products.stock), token-bucket rate limiting on the public API, and a fix for double charges on checkout retry in src/checkout/.
...
```

Without `--agents` the cookbook always runs this demo and never reads your own history. The answer joins both agents' work. The order history page comes from a Claude Code session, and the overselling fix comes from a Codex session. The run then prints a `Claude Code only` answer and a `Codex only` answer, each about its own agent's sessions. The demo uses its own dataset, `imported_agent_sessions_demo`, so it never mixes with your history.

## Run It on Your Data

* Claude Code or Codex history on this machine. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` point the cookbook at moved history folders, as they do for the agents.
* An LLM key in `.env`. Besides `LLM_API_KEY`, an `OPENAI_API_KEY` or an `ANTHROPIC_API_KEY` works too; when several are set, the first in that order wins. With an Anthropic key, cognee runs on `claude-haiku-5-5`. Embeddings stay local with every key. Every imported session is sent to that key's provider.

```bash theme={null}
uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py --check
uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py --agents claude,codex
uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py --agents claude,codex \
  --project ~/code/cognee --ask "Which tickets did I work on?"
```

`--check` lists the agents it found, their sessions and the project folders they were started in, and reports what is missing without importing anything. `--agents` names whose history to import: `claude`, `codex` or both. `--project` takes a folder path from the `--check` output. Running it again adds new sessions and skips unchanged ones. The [README](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/README.md#run-it) lists every option, such as `--agents`, `--since` and `--limit`. Later questions don't need a new import: `uv run python examples/cookbooks/import_agent_sessions/scripts/ask.py "..."`.

## How It Works

### Step 1: Start From an Empty Memory

Source: [`scripts/clear.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/scripts/clear.py)

This step forgets what an earlier run imported. It runs only with `--clear`, which a demo run always turns on.

```python theme={null}
await clear(dataset)
```

cognee's part is one call: [`cognee.forget(dataset="imported_agent_sessions")`](/core-concepts/main-operations/forget), which deletes the dataset and everything extracted from it. Your files in `~/.claude` and `~/.codex` are never touched.

### Step 2: Read Each Agent's History

Source: [`scripts/read_sessions.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/scripts/read_sessions.py)

This step reads the newest 20 sessions of each chosen agent, not your whole history; pass `--limit N` to change how many. `--project` and `--since` narrow it to one repo or period.

```python theme={null}
sessions = read_sessions(agent, args.limit, args.project, args.since)
```

It keeps your prompts and the agent's final answers, and drops tool calls, thinking, subagents and the instructions the harness injects. Secrets become `[redacted]`: text in the format of a known key or token, the password in a URL, and the value assigned to a name that says it is secret, such as `DB_PASSWORD=...`. It skips a session changed in the last two minutes, because that is a session still running, such as the one importing. No LLM and no cognee are used.

### Step 3: Write One File per Session

Source: [`scripts/read_sessions.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/scripts/read_sessions.py)

This step saves each session as a Markdown file in `sessions/<agent>/`, so you can read exactly what cognee will get.

```python theme={null}
write_sessions(sessions, agent, out)
```

Each file holds the session's folder, git branch, start time and title, then its turns. The folder is git-ignored. Redaction catches common key formats only, so open a few files before you import a lot.

### Step 4: Remember the Sessions

Source: [`scripts/ingest_sessions.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/scripts/ingest_sessions.py)

This step saves every chosen agent's sessions into one memory, so a question can see them all at once.

```python theme={null}
await ingest_sessions(args.agents, dataset, out)
```

cognee's part is one [`cognee.remember`](/core-concepts/main-operations/remember) call per agent, into the [*dataset*](/core-concepts/further-concepts/datasets) `imported_agent_sessions`, the named memory everything goes into. Each call tags its files with a [*node set*](/core-concepts/further-concepts/node-sets), a tag you can later recall from alone: `imported_agent_sessions:claude_code` or `imported_agent_sessions:codex`. The tags carry the dataset's name because, with access control off, all datasets share one graph. A resumed session's earlier copy is forgotten first, so no session is stored twice.

### Step 5: Ask Over Every Agent, Then Each

Source: [`scripts/ask.py`](https://github.com/topoteretes/cognee/blob/dev/examples/cookbooks/import_agent_sessions/scripts/ask.py)

This step answers your question over all chosen agents, then over each agent alone.

```python theme={null}
await ask(args.ask, args.agents, dataset)
```

Each answer is one [`cognee.recall`](/core-concepts/main-operations/recall) with `HYBRID_COMPLETION`, which answers from the matching session passages and the graph around them. `node_name` picks the node sets: every agent's for the first answer, one agent's for each of the others. Each answer runs in a new [*session*](/guides/persistent-memory-across-sessions), cognee's short-term memory for one conversation, so earlier answers never leak into it.

## Make It Yours

* **Change what it answers.** Edit `PROMPT` in `scripts/ask.py` to get a standup of last week's work, or a list of files touched per ticket.
* **Import one project.** Pass `--project <repo folder>` and `--since YYYY-MM-DD`, then raise `--limit` once the answers look right.
* **Ask from your coding agent.** Have the agent run `scripts/ask.py` before it starts a task, so it opens with what you and the other agent already did in that repo.

## Clean Up

```bash theme={null}
export EMBEDDING_PROVIDER=fastembed EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 EMBEDDING_DIMENSIONS=384
uv run cognee-cli forget --dataset imported_agent_sessions
uv run cognee-cli forget --dataset imported_agent_sessions_demo
```

The `export` line matters: cognee refuses to open a dataset with a different embedding model than the one it was built with, and the cookbook builds both datasets with fastembed. If your `.env` sets `EMBEDDING_PROVIDER`, cognee uses that instead, which is what the cookbook used too.

To also delete the files the cookbook wrote, remove `sessions/` and `sample/` in the cookbook folder.

## The Claude Code and Codex Plugins

The cognee [Claude Code](/cognee-cloud/agent-integrations/claude-code) and [Codex](/cognee-cloud/agent-integrations/codex) plugins record new sessions from the moment they are installed. They don't see this import yet. They run their own cognee server with its own database, recall from their own dataset (`agent_sessions` by default), and list only recorded sessions in their recap and standup.

> **[Self-Hosted AI Companion](/cookbooks/self-hosted-companion)**
>
> Build another one: a companion that knows your notes.

> **[NodeSets](/core-concepts/further-concepts/node-sets)**
>
> How a tag lets you recall from one part of a dataset.

> **[Recall](/core-concepts/main-operations/recall)**
>
> The search types behind each answer.

> **[Claude Code with Cognee Cloud](/cognee-cloud/agent-integrations/claude-code)**
>
> Record new Claude Code sessions as they happen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.