Metadata-Version: 2.4
Name: claude-lore
Version: 0.1.1
Summary: Turn your Claude Code sessions into a LORE.md file your whole repo can read.
Project-URL: Homepage, https://github.com/inspirationnation635-sketch/lore
Project-URL: Repository, https://github.com/inspirationnation635-sketch/lore
Project-URL: Issues, https://github.com/inspirationnation635-sketch/lore/issues
Author: Tyler
License: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,documentation,knowledge
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.39.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# lore

> Turn your Claude Code sessions into a `LORE.md` file your whole repo can read.

Every Claude Code session you run leaves behind a JSONL file in `~/.claude/projects/`. They contain real knowledge — bug fixes you found, architecture decisions you made, gotchas the AI bumped into. That knowledge dies in your home directory.

`lore` distills those sessions into a `docs/LORE.md` file *inside the repo itself*, so:

- Knowledge is **git-tracked** — versioned, diffable, mergeable
- Knowledge **moves with the project** — clone the repo, get the context
- **Multiple devs** on the same project all feed the same `LORE.md`
- New people onboarding read `LORE.md` first and skip a week of confused poking

## Quick start

```bash
# install
pipx install claude-lore

# from inside any git repo
lore extract        # reads relevant sessions, appends to docs/LORE.md
```

That's it. Run it again anytime — it remembers what it's already processed.

### Auto mode (recommended)

```bash
lore install-hook
```

This adds a Claude Code Stop hook to `~/.claude/settings.json`. From then on, every time a Claude Code session ends, lore extracts it in the background and appends to the relevant repo's `LORE.md`. Set it once, never think about it again.

Uninstall any time with `lore uninstall-hook`.

### How it talks to Claude

Two backends, auto-selected:

- **CLI (default)** — shells out to your local `claude --print`. Free if you have a Claude Code subscription. No API key needed.
- **API** — falls back to the Anthropic SDK if `claude` isn't installed. Set `ANTHROPIC_API_KEY` in your env.

Force one with `--backend cli` or `--backend api`.

## What it captures

Not chat transcripts. Not summaries. Specifically:

- **Decisions** — "We use X over Y because Z"
- **Gotchas** — "If you change A, B will silently break"
- **Patterns** — "This codebase tends to do X by Y convention"
- **Workarounds** — "Library Q has a bug with R; we work around it via S"
- **Domain knowledge** — "User accounts on this system have these states: …"

It deliberately *doesn't* capture: session blow-by-blow, debugging detours that didn't pan out, generic AI chitchat.

## Configuration

Drop a `.lore.toml` in your repo root:

```toml
[output]
path = "docs/LORE.md"          # where the lore file lives
style = "categorized"          # or "chronological"

[extraction]
model = "claude-sonnet-4-6"    # which Claude to use for distillation
since = "30d"                  # only process sessions in last 30 days
backend = "auto"               # "cli" | "api" | "auto"

[filter]
min_messages = 6               # skip tiny sessions
exclude_patterns = ["*test*"]  # skip sessions whose prompts match these
```

All fields are optional. Defaults are sensible.

## Commands

```bash
lore extract              # extract from all unprocessed sessions for this repo
lore extract --since 7d   # only sessions in last 7 days
lore extract --session ID # extract just one session by ID
lore extract --quiet      # suppress progress output (writes still print)
lore preview ID           # extract one session, print to stdout, don't write (dry run)
lore status               # show which sessions are processed/pending
lore init                 # create a starter .lore.toml
lore install-hook         # auto-extract on every Claude Code session end
lore uninstall-hook       # remove the auto-extract hook
```

## What real output looks like

Run `lore preview` against any of your past sessions to see what it'd write. Here's the actual output from one of mine — a session where I'd debugged a TTS gotcha in a voice-assistant repo:

```markdown
### Decisions

- `extract_spoken` in `~/axel/axel.py` strips fenced code blocks, inline backtick
  spans, and shell-prompt lines (`$`, `#`, `>`, paths) from the fallback text
  before TTS. Why: the fallback was reading raw terminal output and code aloud
  when no `SAY:` line was present.

### Gotchas

- The `SAY:` convention in Axel replies is load-bearing for TTS quality. If the
  assistant omits `SAY:` lines, `extract_spoken` falls back to the full reply —
  even with code fences. The stripping heuristic catches most cases but isn't a
  substitute for always tagging spoken lines.
- After patching `axel.py`, the daemon must be **reloaded** (not just signaled) —
  the old code stays in memory until the LaunchAgent restarts the process.
  Reload via `launchctl` against `io.tyler.axel.daemon`.

### Domain

- `~/axel/axel.py` is the voice loop daemon. Pipeline per turn:
  mic → wake word → record → Whisper → agent → `extract_spoken` → `say` → speakers.
- The Axel daemon registers three LaunchAgent labels:
  `application.io.tyler.axel.<pid>.<pid>` (session),
  `io.tyler.axel.daemon` (main background loop),
  `io.tyler.axel.menubar` (menu-bar UI). Target `io.tyler.axel.daemon` for reload.
```

That's two short bug-fix sessions distilled — versioned in the repo, future-you (or a teammate) reads `LORE.md` and skips the rediscovery.

## How does this differ from X?

| Tool | What it does | What `lore` does differently |
|---|---|---|
| crune | Semantic graph of all your sessions, surfaces skills | Personal vault, not in-repo |
| obsidian-second-brain | Sync notes to Obsidian | Personal vault, not in-repo |
| claude-conversation-extractor | Dump JSONL → Markdown | Raw transcripts, not distilled knowledge |
| claude-history | Search/browse sessions in TUI | Read/search, doesn't write |

`lore`'s wedge: **in the repo, distilled to what matters, auto-maintained.**

## License

MIT

## Status

v0.1 — works, ship it. Built by [@inspirationnation635-sketch](https://github.com/inspirationnation635-sketch) with [Axel](https://anthropic.com/claude).
