Tools
Karpathy Claw
By Deterministic markdown-first knowledge compiler plugin and compiler workflow for OpenClaw.
Install
npm install
```README
# Karpathy Claw
Karpathy Claw is an unofficial [OpenClaw](https://github.com/openclaw/openclaw) plugin and compiler that turns Andrej Karpathy's [`llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) idea into a working, local-first knowledge system.
It is called:
- `Karpathy` because the repo is directly inspired by Karpathy's public LLM wiki pattern
- `Claw` because the implementation is built as an OpenClaw plugin plus a markdown/wiki compiler
This is not Andrej Karpathy's code, not an official implementation, and not affiliated with or endorsed by him.
## Why this repo exists
Karpathy's gist describes a pattern that is different from classic RAG:
- preserve raw sources immutably
- maintain a markdown wiki that compounds over time
- query the wiki first
- use `index.md` and `log.md` as durable navigation and memory surfaces
- file good answers back into the wiki instead of letting them die in chat history
Karpathy Claw implements that pattern inside OpenClaw with a one-writer compiler, a pluggable maintainer step, and a fixture-first test path.
## Attribution
Primary concept source:
- [Andrej Karpathy's `llm-wiki.md` gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
Helpful Andrej Karpathy links:
- [GitHub](https://github.com/karpathy)
- [Gists](https://gist.github.com/karpathy)
- [Website](https://karpathy.ai/)
- [Blog](https://karpathy.github.io/)
- [X](https://x.com/karpathy)
OpenClaw references:
- [OpenClaw repository](https://github.com/openclaw/openclaw)
- [OpenClaw docs](https://github.com/openclaw/openclaw/tree/main/docs)
## What is proven
- deterministic ingest from an OpenClaw tool/skill path
- immutable raw packet storage under `raw/packets/<id>/`
- preserved original artifacts for URLs and attachments
- one-writer wiki compilation into `wiki/sources`, `wiki/concepts`, `wiki/projects`, `wiki/entities`, `wiki/syntheses`, `wiki/promoted`, and `wiki/notes`
- an explicit maintainer seam, with `deterministic-v1` as the current honest default
- richer `wiki/index.md` catalog rebuilds
- append-only `wiki/log.md` entries for ingest, query, promotion, filing, dream, and lint operations
- wiki-first query with raw fallback when trusted wiki evidence is weak
- explicit promotion, dream seeds, linting, and filing-good-answers-back surfaces
- attachment parsing with parser fallback for markdown, text, and binary-first cases such as PDFs
- fixture-driven local tests plus a native OpenClaw plugin entry
## What is still intentionally minimal
- the compile pass now has a pluggable maintainer step, but the default maintainer is still deterministic and local-first, not yet a true external-model wiki maintainer
- live fetch is guarded and optional rather than production-grade
- attachment parsing is broader than Phase 1 but still early
- contradiction handling and richer synthesis policies are still lightweight
- installability is stronger than the original prototype, but this is still best thought of as a sharp public prototype instead of the final reference implementation
## Repo layout
```text
docs/
archive/
fixtures/
packages/
compiler/
openclaw-plugin-karpathy-claw/
scripts/
```
## Quickstart
1. Install dependencies:
```bash
npm install
```
2. Run verification:
```bash
npm run typecheck
npm test
```
3. Read the local setup docs:
- [OpenClaw local dev](docs/openclaw-local-dev.md)
- [Build spec](docs/build-spec.md)
- [Architecture](docs/architecture.md)
4. If you want a repeatable local smoke flow, use:
```bash
./scripts/smoke-local-plugin.sh
```
## Packages
### `@karpathy-claw/compiler`
Owns:
- capture normalization
- packet schemas and dedupe identity
- immutable packet/original writes
- wiki compilation, maintainer orchestration, and catalog rebuilds
- wiki-first query with raw fallback
- promotion, dream, lint, and file-back operations
### `@karpathy-claw/openclaw-plugin-karpathy-claw`
Owns:
- native OpenClaw plugin manifest and entrypoint
- deterministic tool registration
- maintainer-mode configuration
- slash-command raw-argument adapters
- fixture-backed capture and guarded live fetch
## Documentation
- [Architecture](docs/architecture.md)
- [Build spec](docs/build-spec.md)
- [Packet schema](docs/packet-schema.md)
- [Page schema](docs/page-schema.md)
- [Test plan](docs/test-plan.md)
- [Progress log](docs/progress-log.md)
- [Next-phase plan](docs/progress-log-2.md)
- [Archived GPT-5.4 Pro handoff](docs/archive/gpt-5.4-pro-handoff)
## License
[MIT](LICENSE)
tools
Comments
Sign in to leave a comment