llm-wiki-ops

Graph-level operations for Karpathy LLM Wiki knowledge bases.

Lets LLM agents (via MCP) and humans (via CLI) perform structured graph surgery on a wiki: node/edge CRUD, wikilink management, index rebuilding, and graph metrics — all as pure file operations with zero LLM, Tauri, or network dependencies.

Features

• Node ops — add, update, rename, delete wiki pages with frontmatter and wikilink management

• Edge ops — add/remove edges between pages via dual carriers ([[wikilink]] + related[]), idempotent

• Metrics — topology (degree, hubs, connected components, fragmentation), source overlap / near-duplicate detection, cross-type edge matrix, type distribution

• Index maintenance — rebuild index.md type sections while preserving custom content

• Concurrency — wiki-level proper-lockfile write lock + optimistic mtime/size/sha256 checks

• MCP server — expose all operations as MCP tools for LLM agent integration

• CLI — llm-wiki-ops command for human/script use

• A2A server — expose the 7 agents to other agents over the standard A2A protocol (JSON-RPC + SSE)

• Plan agent — turn a one-line goal into a full recursive work plan (giant Markdown outline), validated by hard constraints and optionally sourced from the knowledge graph (see docs/design/plan-agent.md)

Related MCP server: OpenCode LLM Wiki MCP Server

Plan Agent（规划智能体）

Recursive splitting is outline generation: plan takes a one-line goal and recursively decomposes it into a giant Markdown outline, where every heading is a node carrying five fields (> 目标： / > 角色： / > 配额： / assessment / negotiation log). The output is parsed and serialized through a lossless MD-AST.

llm-wiki-ops plan "AI 就业影响深度研究报告" --wiki economic-analysis \
  --log-negotiation --dry-run --json

Structured scoring table (结构化评分表) — every non-leaf node (parent) carries a 100-point table evaluating its children:

> 考核｜总分 100
> 考核项｜锚定图谱证据｜20｜父层定
> 考核项｜口径完整与数据可审计｜20｜父层定
> 考核项｜论证逻辑自洽｜20｜父层定
> 考核项｜与同级章节衔接｜20｜子上报
> 考核项｜新增价值与增量贡献｜20｜子上报

• Total is always 100 (conserved per node, enforced by the validator).

• Two setters: 父层定 (decided by the parent) and 子上报 (proposed jointly by all sibling children and merged into the shared table) — each child is scored against the whole shared table, part of which is set by its siblings, creating peer-level incentive/checks.

• Leaf nodes carry no table; the legacy single-line > 考核： still parses (backward compatible).

Validation gate — every written .md is parsed and validated after each iteration; hard violations (level jumps, quota mismatches, missing assessment tables, non-100 totals, missing negotiation notes) are fed back to the agent in the loop, and the final plan is anchor-checked against the graph (🔗 锚点：N 个 @引用全部命中图谱).

Delivered big-plan example (2026-08-16) — economic-analysis graph (1159 nodes) → wiki/plans/ai就业影响深度研究报告撰写计划.md: 37 nodes (8 non-leaf + 29 leaf), 8 × 100-point scoring tables (40 items: 25 父层定 + 15 子上报), 39 deduplicated @ references all hit the graph, validatePlan passes (incl. C6 scoring-table rules).

Install

npm install llm-wiki-ops

CLI

Wiki root is resolved from --wiki <path> or the SELECTED_WIKI environment variable — no need to repeat it on every command.

# Set once, use everywhere (path or a slug under WIKIS_ROOT)
export SELECTED_WIKI=/path/to/my-wiki

# Or manage multiple wikis: set WIKIS_ROOT to the directory holding them,
# then select one (also enables cross-wiki search on read commands)
export WIKIS_ROOT=/path/to/wikis
llm-wiki-ops use my-wiki      # writes SELECTED_WIKI=my-wiki
llm-wiki-ops status           # show current resolution

# Add a node
llm-wiki-ops add-node --title "My Page" --type concept

# Add an edge (idempotent — ensures both [[wikilink]] and related[])
llm-wiki-ops add-edge my-page other-page

# Query a subgraph
llm-wiki-ops read --type concept --depth 2

# Graph metrics
llm-wiki-ops metrics --json

# Rebuild index
llm-wiki-ops rebuild-index

# Override wiki root per-invocation
llm-wiki-ops --wiki /other/wiki stats

MCP Server

wiki-graph-mcp --wiki ./my-wiki

Default wiki resolution (when --wiki is omitted):

--wiki <path-or-slug>  >  SELECTED_WIKI env  >  WIKI_ROOT env (deprecated)  >  error

SELECTED_WIKI is the same variable the CLI reads, so a shell where llm-wiki-ops works also works for the MCP server. It accepts a full path or a slug resolved against WIKIS_ROOT. WIKI_ROOT still works as a fallback but prints a deprecation warning.

Configure in your MCP client:

{
  "mcpServers": {
    "llm-wiki": {
      "command": "wiki-graph-mcp",
      "args": ["--wiki", "/path/to/wiki"]
    }
  }
}

Or bind the default wiki via env instead of --wiki:

{
  "mcpServers": {
    "llm-wiki": {
      "command": "wiki-graph-mcp",
      "env": { "SELECTED_WIKI": "/path/to/wiki" }
    }
  }
}

Individual tools also accept an optional selected_wiki argument to target a different wiki for that one call (a full path or a slug under WIKIS_ROOT).

A2A Server（智能体协作）

7 个 CLI 智能体（ingest / research / purge / check / reason / plan / dream）可以通过标准 A2A 协议 暴露给其他 agent 远程调用：发一条消息 → 建任务 → 轮询/SSE 订阅 → 取回结论。内部复用同一套 agent 运行时（图仍是唯一通信渠道），只是把"本机 shell 调用"变成"网络上的一次调用"。

import { startA2aServer } from "llm-wiki-ops/a2a"

const { url, close } = await startA2aServer({ wikiRoot: "/path/to/wiki" })
// url = http://127.0.0.1:4317

• 发现：GET / 目录页；GET /a2a/<skill>/.well-known/agent-card.json 发布 AgentCard（skills 清单 + capabilities + environment 扩展字段：6 个内建工具 + 13 个 MCP 工具的自述目录）

• 调用：JSON-RPC 2.0 —— message/send（建任务）、tasks/cancel；任务状态机 submitted → working → completed / failed / canceled

• 流式：message/stream / tasks/subscribe / tasks/resubscribe 走 SSE，任务到终态流自动关闭

• 安全边界：本机信任域（默认 127.0.0.1，无鉴权）——不要暴露到公网

• 状态：HTTP server / AgentCard / JSON-RPC / SSE / 7 个 agent 适配器已实现；llm-wiki serve CLI 命令待接

设计文档：docs/design/a2a-agent-protocol.md（v1 已定案：拓扑、任务模型、运行时、分阶段计划）。

Library

import { WikiGraph } from "llm-wiki-ops"

const wiki = new WikiGraph("/path/to/wiki")
await wiki.validate()

// CRUD
await wiki.addNode({ title: "My Page", type: "concept" })
await wiki.addEdge("my-page", "other-page")

// Metrics
const metrics = await wiki.getMetrics()
console.log(metrics.topology.hubs)
console.log(metrics.sourceOverlap.duplicateClusters)

await wiki.cleanup()

Usage log (on by default)

Every read and write through WikiGraph appends one JSONL event to <wikiRoot>/.llm-wiki-ops/usage/YYYY-MM-DD.jsonl. It powers the "what is actually used / what has been forgotten" signal behind llm-wiki graph usage, the usage_stats MCP tool, and the dream agent's node selection.

maintainLog defaults to true — a change in behaviour for library consumers, who previously got no log. Pass false to opt out (tests and read-only tooling usually want this):

const wiki = new WikiGraph("/path/to/wiki", {
  maintainLog: false,      // no usage log
  actor: "my-app",         // who is operating, recorded in each event
})

// Buffered read events are flushed on a timer; flush explicitly before exit.
await wiki.flushUsageLog()

Day files older than 90 days are pruned automatically, and the directory sits outside wiki/ so it never shows up in the graph.

Wiki Structure

Operates on the standard LLM Wiki layout:

my-wiki/
├── wiki/
│   ├── index.md
│   ├── entities/
│   ├── concepts/
│   ├── sources/
│   ├── queries/
│   ├── comparisons/
│   ├── synthesis/
│   └── overview/
├── raw/
├── purpose.md
└── schema.md

Development

npm install
npm run typecheck
npm test
npm run build

Live tests

npm test is fast, offline and deterministic. It also cannot catch bugs that live in the seam between components — a real one made the forgetting ladder's last step unreachable while all 413 unit tests stayed green.

npm run test:live runs one real dream: real model, real MCP subprocess, real disk, on a throwaway copy of a real wiki.

npm run build          # live tests spawn the compiled MCP server
npm run test:live

Requirements — it skips (does not fail) when they are missing:

• OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL_NAME in .env

• a source wiki, overridable with WIKI_LIVE_SOURCE=/path/to/wiki

Costs minutes and real API spend per run, so it is deliberately outside npm test.

Every assertion is an invariant — something that must hold no matter what the model decides. How many edges it writes and what it compresses are its judgement, and asserting those would produce a suite that fails whenever the model behaves reasonably but differently. What is asserted: the run completes, writes stay in scope, compression moves at most one rung per node, only skeleton nodes get deleted, sources/overview are never deleted, no new dangling wikilinks appear (the source wiki already has hundreds — the test is incremental), the journal records what pure code injected, and a dream's own writes do not inflate the next dream's pressure.

Keep artefacts for inspection with WIKI_LIVE_KEEP=1; the temp wiki is otherwise deleted after the run. The source wiki is only ever read.

License

MIT