llm-wiki 1.0

1. the problem: agent memory is temporary

you spend an afternoon teaching an agent how a project works. it reads the source material, learns your preferences, finds the edge cases, and reaches a useful conclusion. then the session compacts, the terminal closes, or you switch tools. the next session starts mostly from zero.

saving the transcript is not enough. transcripts mix facts with guesses, dead ends, tool chatter, and decisions that were later reversed. dumping every old conversation into a new prompt is expensive and noisy. a useful memory system has to separate evidence from synthesis, current knowledge from operational context, and durable decisions from temporary conversation.

llm-wiki makes that separation explicit. original material goes into an immutable raw layer. agents compile it into short, linked articles. indexes make the collection navigable. operational memory lives beside the knowledge base instead of pretending to be evidence. when something changes, the affected material can be refreshed without rewriting history.

2. install on five runtimes

version 1.0 packages the same workflow for Claude Code, OpenAI Codex, DeepSeek Harness, OpenCode, and portable Agent Skills/Pi-style hosts. the host supplies the model and tools; llm-wiki supplies the knowledge protocol.

Claude Code

claude plugin marketplace add nvk/llm-wiki
claude plugin install wiki@llm-wiki

OpenAI Codex

codex plugin marketplace add nvk/llm-wiki
codex plugin add wiki@llm-wiki
# start a new thread, then use @wiki or $wiki-query

DeepSeek Harness

git clone https://github.com/nvk/llm-wiki.git
cd llm-wiki
./scripts/install-deepseek-harness.sh --verify

OpenCode

{
  "instructions": [
    "https://raw.githubusercontent.com/nvk/llm-wiki/master/plugins/llm-wiki-opencode/skills/wiki-manager/SKILL.md"
  ]
}

portable agents and Pi

load plugins/llm-wiki-opencode/skills/wiki-manager/SKILL.md as an Agent Skill, or copy the bundled AGENTS.md into a project. native commands become natural-language requests, but the storage and provenance rules stay the same.

create the first topic

/wiki init research-notes

Codex users can say @wiki initialize a topic named research-notes. by default, the hub lives at ~/wiki/; set hub_path in ~/.config/llm-wiki/config.json to use a private synced directory instead.

3. how the wiki is organized

the hub is only a registry. each subject gets an isolated topic wiki, so a product research corpus does not leak into a gardening query just because both happen to mention “growth.”

~/wiki/
├── wikis.json              # topic registry with stable wiki identities
├── _index.md               # hub navigation
├── .sessions/              # optional redacted operational memory
├── .skills/                # optional personal specialist methods
└── topics/
    └── product-research/
        ├── raw/            # immutable source notes and revisions
        ├── wiki/           # compiled concepts, topics, and references
        ├── inventory/      # things, Ideas, queues, and next actions
        ├── datasets/       # manifests for large or external data
        ├── output/         # reports, plans, comparisons, checkpoints
        ├── schema.md       # human-owned topic guide
        ├── _index.md
        └── log.md

articles use both Obsidian wikilinks and normal Markdown links. the vault stays readable in a text editor, browsable in Obsidian, and easy for an agent to follow without a proprietary database.

4. one fuzzy entry point

you do not need to memorize the command taxonomy. start with /wiki in Claude Code or @wiki in Codex and describe the outcome. the router inspects the request and chooses the narrowest workflow that fits.

@wiki add this paper to the ergonomics topic
@wiki what do we know about display glare and eye strain?
@wiki collect examples of repairable desk lamps
@wiki turn the adjustable-lighting idea into a researched brief
@wiki where did we leave off on the supplier review?
@wiki audit the onboarding report before I share it

explicit commands remain useful for scripts and repeatable operations, but the normal interface is intent-first. a URL routes to ingestion; a question routes to query; “find examples” routes to collection; a rough proposal routes to Ideas; “where did we leave off?” routes to session rehydration.

5. feature map

• research: run parallel searches from academic, technical, practical, current, and contrarian angles, then ingest and compile the useful material.
• ingest and compile: accept URLs, files, prose, inboxes, Git documentation, message archives, MediaWiki sources, and pinned manifest-only repository snapshots.
• query: answer from indexes and compiled articles at quick, standard, or deep scope, while surfacing relevant sibling-topic connections.
• collect: find and deduplicate examples, tools, media, entities, or candidate sources; keep provenance for where each item was found.
• Ideas and Projects: capture a rough thought, research and challenge it, shape a brief, then require explicit promotion before it becomes delivery work.
• inventory: track durable items, queues, candidates, watch lists, owners, and next actions without confusing them with source evidence.
• datasets: register large or external corpora with manifests, fields, samples, limitations, and query recipes.
• audit and librarian: trace claims back to sources, check freshness and article quality, find structural drift, and research gaps when the local corpus is insufficient.
• outputs: build reports, comparisons, study guides, timelines, slide outlines, and implementation plans from the compiled wiki.
• checkpoints: create privacy-scanned, hash-verified project handoffs with explicit source and section coverage. checkpoint creation never authorizes a commit or publication.
• specialists: apply user-owned review methods—such as research-methodology or editorial checks—without pretending the model has professional credentials.
• archive and retract: hide inactive topics without deleting them, or explicitly remove a bad source and repair its downstream references.

6. session capture and rehydration

rehydration solves a different problem from knowledge retrieval. the wiki may know everything about a project while the new chat still does not know what you were doing five minutes before the old session ended.

when trusted hooks are enabled, balanced capture writes compact, redacted digests under .sessions/. it records harness metadata, working directory, Git context, small tool events, decisions, and pointers—not full transcript bodies by default. a later session can recover the relevant thread without pasting weeks of chat history into the prompt.

/wiki:session status
/wiki:session capture
/wiki:session rehydrate --cwd "$PWD"
/wiki:session promote codex:abc123 --topic product-research
/wiki:session disable

rehydrated context remains operational memory. promoting a distilled digest into raw/notes/ is an explicit step. high-signal corrections and preferences follow the same rule: they become reviewable feedback candidates first, not silent permanent memory.

7. private adapters

some work involves external systems: a private document store, an authenticated provider, or a workflow that can make remote changes. baking those credentials and provider-specific steps into a public wiki plugin would collapse the security boundary.

llm-wiki therefore keeps adapters local and content-free. the machine-local registry stores the executable, permitted input/output roots, declared URL routes, and environment-variable names. real inputs, outputs, credentials, and receipts stay in the adapter's private data plane.

./scripts/llm-wiki adapter add /private/adapter   --read-root /private/input --write-root /private/results
./scripts/llm-wiki adapter list
./scripts/llm-wiki adapter show example-adapter
./scripts/llm-wiki adapter doctor example-adapter
./scripts/llm-wiki adapter route --intent read   --resource 'https://provider.example/document/123' --json
./scripts/llm-wiki adapter run example-adapter   --request /private/input/request.json --json

a route match is discovery, not authorization. remote writes require the exact approved plan hash, a stable request, an adapter-owned apply operation, and a verified private receipt. adapter output is not automatically imported into a topic; only a reviewed wiki-safe candidate enters the normal provenance pipeline.

8. what 1.0 guarantees

the 1.0 label is about stable identity and honest provenance, not a promise that every optional field is mandatory. the supported baseline now includes:

• stable wiki identity: a wiki_id helps detect a registry path that silently points at the wrong corpus.
• auditable engine identity: lint reports can include the engine version and commit, with optional corpus pins for CI gates.
• human-only verification: agents may update operational freshness fields, but they do not mark evidence verified on a person's behalf.
• immutable refresh history: changed upstream content creates a new revision with supersedes lineage instead of mutating the original source note.
• coverage integrity: lint checks raw ownership, footnotes, wiki links, nested raw namespaces, indexes, and archive registry drift.
• pinned collection ingestion: Git imports can store a manifest with exact paths and blob hashes for a selected revision, without copying every child body.
• portable packaging: native DeepSeek Harness skills and Windows-compatible Codex hook launchers join the Claude, Codex, OpenCode, and portable-agent surfaces.

9. when to use it

use llm-wiki when

• the work must survive a session, model, or agent switch;
• answers need traceable sources and an honest freshness story;
• you repeatedly research the same domain and want each pass to build on the last;
• you need durable Ideas, datasets, inventories, decisions, or project handoffs—not just chat history;
• you want local Markdown that remains useful without this week's preferred model vendor.

skip it when

• the question is disposable and will never be revisited;
• you need low-latency search across millions of rapidly changing records—use a database or retrieval system, and let the wiki document how to query it;
• nobody will maintain source freshness or review generated synthesis. durable wrongness is worse than an ephemeral answer.

llm-wiki is not a replacement for databases, source control, or judgment. it is the connective layer that lets an agent recover context, follow evidence, and leave the next session with something better than another transcript.