claude-conversation-manager/README.md

A CLI tool for managing Claude Code conversation history with parsing and i18n support

# Claude Conversation Manager

Lightweight agent memory manager for Claude Code sessions.

Claude Conversation Manager (CCM) helps you inspect Claude Code JSONL history, repair damaged session files, and extract useful project memory into `.claude-memory/memory.json` and `.claude-memory/handoff.md`.

CCM is local-first. It does not require a cloud API, embeddings service, or external database for memory search and recall.

## What It Solves

- Recover context from older Claude Code sessions.
- Reduce context loss after compaction by externalizing project memory.
- Search and recall decisions, tasks, files, and known issues.
- Keep history cleanup safe with backups and repair checks.

## Install

```bash
npm install -g claude-conversation-manager
```

Requirements: Node.js 16 or newer and Claude Code session files in the standard `~/.claude/projects` location.

## Memory Commands

Run memory commands inside the project you want to remember:

```bash
cd your-project
ccm memory init
ccm memory build
ccm memory search "keyword"
ccm memory recall "what did we decide about compaction?"
ccm memory handoff
```

Command summary:

- `ccm memory init`: create `.claude-memory/memory.json` and `.claude-memory/handoff.md`.
- `ccm memory build`: scan Claude Code sessions for the current project and rebuild local memory.
- `ccm memory search "keyword"`: keyword-search captured memory items.
- `ccm memory recall "query"`: rank relevant memory with lightweight local similarity.
- `ccm memory handoff`: print the current handoff markdown.

Memory output is stored in:

- `.claude-memory/memory.json`: structured sessions and extracted memory items.
- `.claude-memory/handoff.md`: a compact handoff with goals, decisions, files, issues, next steps, and sources.

## Legacy Conversation Commands

CCM still includes the original Claude Code history cleanup tools:

```bash
ccm list
ccm search "keyword"
ccm delete
ccm delete --corrupted
ccm health
ccm health --fix
ccm interactive
```

Legacy command summary:

- `ccm list`: list Claude Code conversations.
- `ccm search "keyword"`: search conversation metadata and summaries.
- `ccm delete`: select and delete conversations with confirmation.
- `ccm delete --corrupted`: focus deletion on conversations marked corrupted.
- `ccm health`: inspect storage, file sizes, and corruption status.
- `ccm health --fix`: attempt repair for recoverable damaged JSONL files.
- `ccm interactive` or `ccm i`: open the menu-driven interface.
- `backup`: create a manual backup from the interactive menu.

## Safety Notes

- Memory output is written to `.claude-memory` in the current project.
- Cleanup commands create backups by default before destructive operations.
- CCM reads Claude Code JSONL files directly and does not modify them when building memory.
- Close Claude Code before running cleanup or repair commands.