# klaw

A personal AI assistant — Kodelyth's working fork of [Klaw](https://github.com/openclaw/openclaw), extended with a compound-memory stack and a growing skill library.

> klaw is the product/brand; `klaw` is the CLI, package, and config namespace.
> Built on Klaw — all upstream architecture, channels, and providers apply.
> Upstream changelog history is preserved at the bottom of `CHANGELOG.md`.

## What klaw adds on top of Klaw

The klaw-specific layer lives in four roots:

| Root           | What it holds                                               |
| -------------- | ----------------------------------------------------------- |
| `src/klaw/`    | The compound-memory + self-improvement runtime (TypeScript) |
| `klaw-skills/` | Skill library — auto-discovered `SKILL.md` directories      |
| `klaw-agents/` | Agent catalog                                               |
| `klaw-memory/` | BM25 memory store + user model                              |

### The memory & self-improvement stack (`src/klaw/`)

| Module                                              | Role                                                               |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `memory-inject` / `memory-capture` / `memory-decay` | BM25 recall, capture on success, Ebbinghaus-style forgetting curve |
| `personal-graph`                                    | SQLite entity graph (people, projects, repos, tools)               |
| `failure-mining` / `anti-skills-inject`             | Cluster repeated failures into "never do this again" warnings      |
| `reply-reflection`                                  | Per-reply self-critique feeding the failure log                    |
| `heartbeat-curator`                                 | Idle-time background curation                                      |
| `session-bridge`                                    | "Where we left off" cross-session digest                           |
| `skill-creator` / `skill-feedback`                  | Auto-create skills from recurring patterns; track outcomes         |
| `style-shaper` / `user-model-inject`                | Enforce reply style from a learned user model                      |
| `prompt-layers`                                     | Stable/dynamic prompt split for provider-side cache reuse          |
| `proactive-nudges`                                  | Deterministic proactive messages                                   |
| `dedupe-repeated-paragraphs`                        | Safety net against repeated/echoed reply text                      |

## Quick start

```bash
pnpm install          # Node 22.19+ (Node 24 recommended)
pnpm build            # compile to dist/
pnpm klaw gateway     # start the gateway
klaw tui              # connect the terminal UI
```

See `CLAUDE.md` / `AGENTS.md` for the full development, validation, and routing policy.

## Skills

Skills are auto-discovered directories under `klaw-skills/`, each with a
`SKILL.md` (frontmatter `name` + `description` required). They are read at
runtime — no build step. Recent additions:

- `youtube-watcher` — fetch + read YouTube transcripts via `yt-dlp`
- `multi-search-engine` — 16-engine web search via `web_fetch`, no API keys, + WolframAlpha
- `self-improvement` — structured `.learnings/` logging that complements `failure-mining`

## Credits

Built on [Klaw](https://github.com/openclaw/openclaw) (MIT). klaw is a
private Kodelyth fork; upstream remains the source of core architecture.

## License

MIT — see `LICENSE`.
