npm package: @royai21/claude-memory
Description: Live transcription of Claude Code conversations to Markdown. Runs in background, zero config.
Latest version: 1.2.1

# claude-memory

> Save your Claude Code conversations to readable Markdown files, automatically.

[![npm version](https://img.shields.io/npm/v/@royai21/claude-memory.svg)](https://www.npmjs.com/package/@royai21/claude-memory)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why?

Claude Code conversations are valuable - they contain decisions, solutions, and context that you might need later. But they're stored in JSONL format and hard to search or share.

**claude-memory** watches your Claude Code sessions and saves them as clean Markdown files, organized by project and date.

## Features

- **Real-time sync** - Conversations saved as you work
- **Zero config** - Just install and run
- **Organized output** - Files grouped by project and date
- **Readable format** - Clean Markdown with timestamps
- **Lightweight** - Minimal resource usage
- **Non-invasive** - No modifications to Claude Code

## Installation

```bash
npm install -g @royai21/claude-memory
```

## Quick Start

### Option 1: Claude Code Slash Commands (Recommended)

Add these to `~/.claude/commands/`:

**~/.claude/commands/mem.md**
```
Start saving this conversation to Markdown.

Run: claude-memory start && claude-memory status
```

**~/.claude/commands/mem-off.md**
```
Stop saving conversations.

Run: claude-memory stop
```

Then in any Claude Code session:
```
/mem        # Start saving
/mem-off    # Stop saving
```

### Option 2: Terminal Commands

```bash
# One-time sync (process recent conversations and exit)
claude-memory sync

# Watch mode (real-time, Ctrl+C to stop)
claude-memory watch

# Background daemon
claude-memory start
claude-memory stop
claude-memory status
```

## Output

Conversations are saved to `~/claude-conversations/`:

```
~/claude-conversations/
├── my-project_2024-02-27.md
├── my-project_2024-02-26.md
├── another-project_2024-02-27.md
└── .watcher-state.json
```

### Example Output

```markdown
# Claude Conversation - 27.2.2024

---

### **User** (14:32)

How do I add authentication to my Express app?

### **Claude** (14:32)

I'll help you add authentication. Let me first check your current setup...

`[Read]` `[Grep]`

Based on your project structure, I recommend using Passport.js with JWT...
```

## Commands Reference

| Command | Description |
|---------|-------------|
| `claude-memory sync` | Process recent conversations once and exit |
| `claude-memory watch` | Watch in real-time (foreground, Ctrl+C to stop) |
| `claude-memory start` | Start background daemon |
| `claude-memory stop` | Stop background daemon |
| `claude-memory status` | Check if daemon is running |
| `claude-memory help` | Show help |

## How It Works

```
┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
│                        │                                │
│                        ▼                                │
│         ~/.claude/projects/**/*.jsonl                   │
│                        │                                │
└────────────────────────┼────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  claude-memory                          │
│                                                         │
│  1. Watches for new/changed .jsonl files                │
│  2. Parses conversation messages                        │
│  3. Converts to readable Markdown                       │
│  4. Appends to project-specific .md file                │
│  5. Tracks state to avoid duplicates                    │
│                                                         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│           ~/claude-conversations/                       │
│                                                         │
│  ├── project-name_2024-02-27.md                        │
│  ├── project-name_2024-02-26.md                        │
│  └── another-project_2024-02-27.md                     │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

## Configuration

Currently, claude-memory uses sensible defaults:

- **Watch directory:** `~/.claude/projects/`
- **Output directory:** `~/claude-conversations/`
- **State file:** `~/claude-conversations/.watcher-state.json`
- **Logs:** `~/.claude-memory/daemon.log`

## Requirements

- **macOS** (Linux support planned)
- **Node.js** >= 18
- **Claude Code CLI** installed

## Troubleshooting

### Daemon not starting?

```bash
# Check status
claude-memory status

# Check logs
cat ~/.claude-memory/daemon.log

# Try running in foreground to see errors
claude-memory watch
```

### No output files?

Make sure Claude Code has created some conversations:
```bash
ls ~/.claude/projects/
```

### Missing recent conversations?

By default, only conversations from the last 24 hours are processed on startup. Run `sync` again or use `watch` mode.

## Privacy

- All data stays local on your machine
- No external connections
- No telemetry
- Conversations are only read, never modified

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © 2024