Metadata-Version: 2.4
Name: claudemnesia
Version: 0.2.0
Summary: Give Claude total recall of its own un-compacted conversation — extract, search, and recall Claude Code transcripts.
Project-URL: Homepage, https://github.com/darki73/claudemnesia
Project-URL: Repository, https://github.com/darki73/claudemnesia
Project-URL: Issues, https://github.com/darki73/claudemnesia/issues
Author-email: darki73 <apple.zhivolupov@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,compaction,mcp,recall,search,transcript
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: fastembed>=0.3
Requires-Dist: mcp>=1.10
Requires-Dist: numpy>=1.26
Provides-Extra: semantic-openai
Requires-Dist: openai>=1.0; extra == 'semantic-openai'
Provides-Extra: semantic-torch
Requires-Dist: sentence-transformers>=2.2; extra == 'semantic-torch'
Description-Content-Type: text/markdown

# claudemnesia

> *claude-in-claude* — the cure for Claude's amnesia.

Claude Code's `/compact` summarizes a long conversation to save context — but that's
**lossy**: it kills the exact wording, the dead-ends, the things you tried. The full,
un-compacted conversation is still on disk in the `.jsonl` transcript.

**claudemnesia** recovers it. It extracts the real user↔Claude exchange — dropping tool
noise, collapsing pasted log/code dumps so the *vibe* survives — and, over an MCP
server, lets a running Claude **search and recall its own un-compacted conversation**,
right after a `/compact`.

On a real 352 MB transcript: **352 MB → ~7 MB (98% smaller)** — 4,176 messages, 243
dumps classified, 24 compaction markers found.

## Install

```sh
uv tool install .        # everything: CLI + local hybrid search (no torch) + MCP server
claudemnesia --help
```

Local semantic search uses **fastembed** (ONNX, no PyTorch) — a base dependency, so the
default install already has working hybrid search. `'.[semantic-openai]'` /
`'.[semantic-torch]'` add the OpenAI / sentence-transformers embedders.

## Quickstart

```sh
# Extract the latest conversation of the current project to Markdown:
claudemnesia --latest -f md -o conversation.md

# Recall: rank this conversation's turns against a question (cited, sub-second):
claudemnesia --latest --search "what did we decide about the dump threshold?"

# Orient after a /compact — the same surface the MCP tools expose:
claudemnesia --latest --recent 8            # the last 8 turns
claudemnesia --latest --outline             # one-line preview of every ask
claudemnesia --find-across "TODO_MARKER"    # exact search across all your sessions
```

→ Full reference: **[docs/cli.md](docs/cli.md)**

## Recall for Claude itself

Expose claudemnesia over the Model Context Protocol so a running Claude can search its
own transcript — the *claude-in-claude* idea. After a `/compact`, it recalls exactly
what the summary dropped.

```sh
uv tool install .
claude mcp add --transport stdio claudemnesia -- claudemnesia-mcp
```

Everything defaults to the **current** conversation (via `CLAUDE_CODE_SESSION_ID`), so
`recall("what did we decide about X")` just works post-compaction.

→ Tools, the wake-up flow, env vars: **[docs/mcp.md](docs/mcp.md)**

## What it does

- **Extract** — the real exchange, tool-noise dropped, dumps collapsed non-destructively (~98% smaller).
- **Recall** — per-turn search (BM25 + semantic, fused with RRF), cited, no vector DB.
- **Navigate** — `recent` / `outline` / `since-compact`, read a turn, read a hidden dump.
- **Operate** — `list_files` / `list_actions`: what the session *changed*, not just what it said.
- **Across sessions** — *"have I solved this before, in another conversation?"*

## Documentation

- **[CLI](docs/cli.md)** — extract, the navigate/inspect verbs, every option, output formats.
- **[MCP server](docs/mcp.md)** — the recall tools, the post-`/compact` wake-up flow, env vars.
- **[Recall & search](docs/search.md)** — lexical / semantic / hybrid, the embedding cache, cross-conversation.
- **[Architecture & internals](docs/architecture.md)** — signal vs. noise, the classification model, the hexagon, library use.

## Contributing

Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Changes are tracked in
[CHANGELOG.md](CHANGELOG.md).

## License

[MIT](LICENSE).
