Metadata-Version: 2.4
Name: llm-wiki-plus
Version: 2.4.0
Summary: LLM wiki to turn multiple agentic tool sessions into knowledge base for agents and humans
Author-email: Alexander Makarov <4ellendger@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AlexanderMakarov/llm-wiki
Project-URL: Documentation, https://github.com/AlexanderMakarov/llm-wiki/tree/main/docs
Project-URL: Repository, https://github.com/AlexanderMakarov/llm-wiki
Project-URL: Issues, https://github.com/AlexanderMakarov/llm-wiki/issues
Project-URL: Changelog, https://github.com/AlexanderMakarov/llm-wiki/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/AlexanderMakarov/llm-wiki/releases
Keywords: llm-wiki,karpathy,knowledge-base,claude-code,codex,cursor,openclaw,markdown,agentic,static-site,mcp,lightweight,automation,metrics,synthesis,obsidian
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: Pytest
Classifier: Typing :: Typed
Classifier: Natural Language :: English
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown>=3.9
Provides-Extra: highlight
Provides-Extra: graph
Requires-Dist: graphifyy>=0.4.20; extra == "graph"
Provides-Extra: add
Requires-Dist: trafilatura>=2.0.0; extra == "add"
Requires-Dist: markitdown[docx,pdf,pptx,xlsx]>=0.1.2; extra == "add"
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: ruff>=0.15.11; extra == "dev"
Provides-Extra: e2e
Requires-Dist: pytest>=8.4.2; extra == "e2e"
Requires-Dist: pytest-playwright>=0.7.1; extra == "e2e"
Requires-Dist: pytest-bdd>=8.1.0; extra == "e2e"
Requires-Dist: pytest-html>=4.2.0; extra == "e2e"
Requires-Dist: Pillow>=10.0; extra == "e2e"
Provides-Extra: all
Requires-Dist: graphifyy>=0.4.20; extra == "all"
Dynamic: license-file

# llmwiki

Cross-tool, cross-project session memory your coding agents can search and read — via MCP — while you keep a universal local vault of what those agents and tools already know.

[Live demo](https://alexandermakarov.github.io/llm-wiki/) · [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) · [MCP reference](docs/reference/mcp.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-v2.4.0-10B981.svg)](CHANGELOG.md)
[![CI](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/ci.yml)
[![Link check](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/link-check.yml/badge.svg?branch=main)](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/link-check.yml)
[![Wiki checks](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/wiki-checks.yml/badge.svg?branch=main)](https://github.com/AlexanderMakarov/llm-wiki/actions/workflows/wiki-checks.yml)

llmwiki ingests sessions from Claude Code, Codex, Cursor, OpenClaw and others — plus files, folders, URLs, and PDFs you feed in — into a redacted markdown vault. Agents use that vault through the stdio MCP server (`python3 -m llmwiki.mcp`): search, read pages, health/lint, sync, export, and add sources without shelling out. Memory spans tools and projects without living inside a single chat UI. Put the vault somewhere you trust — it is the secure place for that unified store. Humans use the static site for the same vault: open `site/index.html` after `build` to check pipeline state, token and cache metrics, health, usefulness, and which entities and concepts have settled so later sessions can take them as given. Nothing has to stay running for MCP or for reading those files.

## What you get

- **MCP tools for agents** — `wiki_search`, `wiki_read_page`, `wiki_health`, `wiki_sync`, `wiki_export`, `wiki_add` over stdio (JSON-RPC). Wire it once in Claude Code, Cursor, Codex, or any MCP client. See [docs/reference/mcp.md](docs/reference/mcp.md).
- **Scriptable source intake** — `llmwiki add` (CLI) or `wiki_add` (MCP) turns files, folders, URLs, and PDFs into markdown structured for free LLM digest, so bookmarks, cron jobs, or other agents can feed the same vault automatically. Once synthesised, that material is ordinary wiki content — same layer as session-derived pages.
- **A knowledge layer** — `synth` writes source summaries and harvests entity/concept *candidates*. You review those (site `/candidates.html` or CLI) and apply decisions with `llmwiki candidates apply`. That review is a real gate, not an optional extra.
- **A static site for humans** — Home, Analytics, Candidates, Topics, graph, and `Cmd+K` search split into Wiki and Site results. See what the pipeline did, browse settled entities/concepts, and search wiki text with the same literal-match rules agents use. Generated by `llmwiki build`; see the [UI reference](docs/reference/ui.md).
- **A vault you place** — choose a secure directory for the unified store (raw sources, wiki pages, built site). It stays on your machine under a path you control; it is not mixed into the package install.

Page kinds: [docs/reference/page-kinds.md](docs/reference/page-kinds.md). MCP tools: [docs/reference/mcp.md](docs/reference/mcp.md). Site screens: [docs/reference/ui.md](docs/reference/ui.md).

## Install

Requires **Python ≥ 3.12** (CI verifies **3.12** only; newer interpreters are installable but not matrix-tested). Runtime dependency is `markdown` only.

```bash
pip install llm-wiki-plus
llmwiki init --vault ~/llmwiki-vault
```

Point a gitignored `config.json` at the vault so later commands need no `--vault`:

```json
{
  "vault": { "default_path": "/home/USER/llmwiki-vault" }
}
```

From a clone, `./setup.sh` installs the package and reports which agents it can see. The clone itself is not a vault — bare `llmwiki init` / `sync` / `build` against this repository are refused; name `--vault` or `demo`.

**Agent kit** (slash commands and skills) after install:

```bash
llmwiki install-agent-kit --dest ~/.claude
```

That is what a pip user runs so `/wiki-sync` and friends work from *their* project. Point your MCP client at `python3 -m llmwiki.mcp` (same package). See [docs/reference/cli.md](docs/reference/cli.md) and [docs/reference/mcp.md](docs/reference/mcp.md).

The install also drops a small `.llmwiki-agent-kit.json` manifest in `--dest`, recording which files it wrote and their checksums. It is safe — and useful — to commit alongside `.claude/commands/`: it is what lets a later upgrade recognise its own files and remove ones it has retired, while leaving anything you wrote or edited alone.

## The loop

Keep the vault current so agents (MCP) and humans (site) see the same knowledge:

```text
sync / add  →  synth  →  review candidates  →  build
```

```bash
llmwiki sync                         # new transcripts → vault/raw/sessions/
llmwiki add notes.md                 # markdown file → vault/raw/docs/
llmwiki add https://example.com/post # web page
llmwiki add ./paper.pdf              # PDF
llmwiki add ./research-folder/       # folder of docs
llmwiki synth                        # source pages + harvest candidates
# review candidates (CLI apply, or open vault/site/candidates.html after a build)
llmwiki build                        # vault/wiki/ → vault/site/ for human browse + metrics
```

`synth` does not rebuild the site. `build` does — run it when you want Home, Analytics, and HTML refreshed. `candidates apply` rebuilds after a successful batch so `/candidates.html` matches the wiki (`--no-rebuild` skips that). Candidate review is the human gate: a row starts with no decision, Apply assembles `llmwiki candidates apply --vault … --actions '…'`, and only that command writes the wiki.

One-shot: `llmwiki all --graph-engine builtin` runs sync → synth → build → graph → lint. Opt out of a stage with `--no-sync`, `--no-synth`, `--skip-graph`, or `--skip-lint`.

## Agents

One row per agent. **Supplies sessions** = `llmwiki sync` can read its transcript store. **Reads the wiki** = MCP and/or slash commands after `install-agent-kit` (any MCP client can call `python3 -m llmwiki.mcp`). **Core** adapters run on a default `sync` when their store exists; **contrib** adapters need `--adapter <name>` or `adapters.<name>.enabled` in config.

| Agent | Supplies sessions | Reads the wiki | Core or contrib |
|---|---|---|---|
| Claude Code | `~/.claude/projects/*/*.jsonl` | slash commands, MCP | core (`claude_code`) |
| Codex CLI | `~/.codex/sessions/` | `AGENTS.md` workflow, MCP | core (`codex_cli`) |
| ChatGPT | contrib store | MCP | contrib (`chatgpt`) |
| Copilot Chat | VS Code workspaceStorage | MCP | contrib (`copilot_chat`) |
| Copilot CLI | `~/.copilot/session-state/` | MCP | contrib (`copilot_cli`) |
| Cursor IDE | workspaceStorage | MCP | contrib (`cursor`) |
| Cursor CLI | `~/.cursor/chats/` | MCP | contrib (`cursor_cli`) |
| Gemini CLI | `~/.gemini/` | MCP | contrib (`gemini_cli`) |
| Obsidian | markdown vault intake | wikilinks in the vault | contrib (`obsidian`) |
| OpenCode | shared OpenClaw schema | MCP | contrib (`opencode`) |
| OpenClaw | `~/.openclaw/agents/*/sessions/` | MCP | contrib (`openclaw`) |

```bash
llmwiki adapters --wide
llmwiki sync --adapter openclaw
```

## Configuration

Shipped defaults: [`examples/sessions_config.json`](examples/sessions_config.json). Personal overrides: gitignored `config.json` at the clone root, merged on top. Full keys: [docs/configuration.md](docs/configuration.md).

Skip projects or dates with a `.llmwikiignore` next to the vault (one path or glob per line).

## Documentation

| Topic | Link |
|---|---|
| Hub | [docs/index.md](docs/index.md) |
| Install + first vault | [docs/getting-started.md](docs/getting-started.md) |
| MCP server | [docs/reference/mcp.md](docs/reference/mcp.md) |
| Product principles | [docs/maintainers/principles.md](docs/maintainers/principles.md) |
| Page kinds | [docs/reference/page-kinds.md](docs/reference/page-kinds.md) |
| CLI | [docs/reference/cli.md](docs/reference/cli.md) |
| Site UI | [docs/reference/ui.md](docs/reference/ui.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
| Upgrading | [docs/UPGRADING.md](docs/UPGRADING.md) |
| GitHub Pages | [docs/deploy/github-pages.md](docs/deploy/github-pages.md) |

This repository's `CLAUDE.md` and `AGENTS.md` are for people changing llmwiki itself. Vault workflows for users live in the installed agent kit.

## Acknowledgements

- [Andrej Karpathy](https://twitter.com/karpathy) — [LLM Wiki idea](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
- [Pratiyush](https://github.com/Pratiyush/llm-wiki) — original llm-wiki project this repository builds on

## License

[MIT](LICENSE) © Alexander Makarov; originally based on [Pratiyush/llm-wiki](https://github.com/Pratiyush/llm-wiki)
