# Klaw

> Your personal AI assistant — by [Kodelyth](https://kodelyth.com)

Klaw is a continuously learning, autonomous AI assistant platform. It connects
to messaging channels (Telegram, Discord, Slack, WhatsApp, Matrix, and more),
runs locally on your machine, and gets smarter over time through a compound
memory stack and a growing library of self-authored skills.

- **Multi-channel.** One Klaw process serves Discord, Slack, Telegram, WhatsApp,
  iMessage (via BlueBubbles), Matrix, Microsoft Teams, Google Chat, Signal, and
  more.
- **Multi-provider.** Wire it to OpenAI, Anthropic, Google Gemini, Groq, Mistral,
  Z.AI, OpenRouter, Cerebras, DeepSeek, Together, Ollama, LM Studio, and others.
- **Self-improving.** Every successful conversation can become a reusable skill.
  Repeated failures cluster into "never do this again" warnings.
- **Local first.** Runs as a gateway process on your own machine. Your data
  stays with you.

Docs live at [klaw.kodelyth.com](https://klaw.kodelyth.com).

## Install

```bash
npm install -g @kodelyth/klaw
klaw onboard       # guided setup for gateway, workspace, auth, channels
```

Requires **Node 22.19+** (Node 24 recommended).

## Quick start

```bash
klaw setup            # initialize config + workspace
klaw configure        # walk through models, gateway, channels, plugins
klaw gateway          # start the gateway service
klaw chat             # open a local terminal UI
```

Common commands:

```bash
klaw status           # gateway, channels, models, recent sessions
klaw doctor           # diagnose and repair config / channel / plugin issues
klaw channels add     # add a messaging channel
klaw plugins list     # browse enabled plugins
klaw skills list      # browse the skill library
```

## What's inside

Klaw is split into four runtime layers:

| Layer        | Purpose                                                    |
| ------------ | ---------------------------------------------------------- |
| **Gateway**  | WebSocket service that owns auth, routing, and message I/O |
| **Agents**   | LLM-backed runtime that handles each turn                  |
| **Channels** | Plugins that connect to Discord, Slack, Telegram, etc.     |
| **Plugins**  | Extensions for providers, tools, hooks, and capabilities   |

The Kodelyth-specific brain layer adds:

| Module                  | Role                                                       |
| ----------------------- | ---------------------------------------------------------- |
| Compound memory         | 9-store SQLite stack (atomic, semantic, episodic, fade, …) |
| Skill forge             | Auto-author skills from successful workflows               |
| User model              | Per-user style + task profile, persisted across sessions   |
| Failure mining          | Cluster repeated mistakes into anti-skills                 |
| Reply reflection        | Per-turn self-critique feeding the failure log             |
| Heartbeat curator       | Idle-time background memory curation                       |
| Session bridge          | "Where we left off" cross-session digest                   |
| Intent router + planner | Route requests to the right agent / skill                  |
| Scheduler               | Cron-style background jobs                                 |

## Skills

Skills live under `klaw-skills/`, one directory per skill, each with a
`SKILL.md` describing when to activate. Klaw discovers them at runtime, so
adding a new skill is as simple as creating a directory.

Klaw also writes its own skills: after a successful multi-step session, it
distills the workflow into a `SKILL.md` and saves it for next time. Existing
skills get a `SKILL.proposed.md` for diff review.

Browse the library:

```bash
klaw skills list
```

## Plugins

Plugins extend Klaw with channels, providers, tools, hooks, and capabilities.
The official catalog ships with the npm package; install third-party plugins
with:

```bash
klaw plugins install <package-name>
```

## Memory

Klaw's memory stack runs locally in SQLite + (optionally) a vector index.
Memory is captured automatically from successful sessions, semantically
indexed, and recalled on relevant turns. You can also browse and reindex
manually:

```bash
klaw memory status
klaw memory search "deployment notes"
klaw memory index --force
```

## Build from source

```bash
git clone https://github.com/kodelyth/klaw.git
cd klaw
pnpm install
pnpm build
node klaw.mjs --version
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development workflow and
[`AGENTS.md`](AGENTS.md) for the in-repo policy that AI tooling reads.

## Links

- **Docs:** [klaw.kodelyth.com](https://klaw.kodelyth.com)
- **npm:** [@kodelyth/klaw](https://www.npmjs.com/package/@kodelyth/klaw)
- **GitHub:** [kodelyth/klaw](https://github.com/kodelyth/klaw)
- **Website:** [kodelyth.com](https://kodelyth.com)

## License

MIT — see [`LICENSE`](LICENSE).