# Agent History Import

When a project adopts ITHZ-MCP, it can optionally import historical prompt/response records from local agent logs.

Supported local sources are best-effort adapters:

- Codex local session logs;
- Claude/Claude Code local history paths when present;
- Cursor local storage paths when present;
- Antigravity local storage paths when present;
- explicit generic JSON/JSONL/Markdown/text roots.

The importer is conservative:

- discovery is project-scoped by cwd/path markers;
- default command is dry-run;
- write requires `--apply`;
- an existing `project.ithz` from Git is reused and appended, not replaced;
- imported records carry author, author source, source history time, source mtime and import time;
- imported records are summary-only;
- raw full chat capture is not automatic;
- secret-like payloads are redacted or blocked;
- duplicate semantic prompt hashes from the same author are not imported twice;
- the same prompt/response pair from a different author is allowed as a separate audit record.

## Discover

```powershell
python -m ithz_mcp agent-history-discover --project .
```

With explicit roots:

```powershell
python -m ithz_mcp agent-history-discover --project . --source codex --root C:\Users\you\.codex\sessions --author Gobi
```

## Import

```powershell
python -m ithz_mcp archive-import-agent-history --project . --source codex --author Gobi --apply
```

If the repository already contains `project.ithz` from a teammate, the command appends your prompt summaries to that same memory zone. It does not create a second archive unless `project.ithz` is missing.

## Adoption

During project adoption:

```powershell
python -m ithz_mcp archive-adopt-project-workflow `
  --project . `
  --profile gobi `
  --owner Gobi `
  --prompt C:\work\tmp\new_project_prompt.txt `
  --import-agent-history `
  --history-source codex `
  --history-author Gobi
```

This creates or validates `project.md`, creates `project.ithz` if needed, mines workflow Markdown/prompt rules into a workflow profile, then imports project-related prompt/response summaries.

## Storage

Imported summaries are stored inside `project.ithz`:

```text
prompts/prompt_log.jsonl
indexes/prompt_summary_index.json
events/events.jsonl
```

`events/events.jsonl` receives searchable import events so historical prompt summaries can appear in context packs.

Each prompt memory record includes:

- `author`, `author_id`, `author_source`;
- `history_time` from the source log when available;
- `source_mtime_utc` as fallback provenance;
- `imported_at_utc` for the audit import;
- `archive_preexisting`, which is `true` when the import appended to a Git-provided archive.

## Limits

The importer does not claim complete coverage for every external client. Each host stores local history differently and may change its format. If a client path is not found, pass an explicit `--root`.
