A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context. It turns sources, plans, and decisions into inspectable context that agents can recover across sessions without coupling application code to the knowledge system.
Documentation · npm package · Graph guide · Changelog
Bun 1.3.14 or newer and Git are required. The CLI and TypeScript SDK run with Bun. Choose one installation source:
# Canonical, versioned GitHub archive
bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.2/hraness-wordcell-0.21.2.tgz
wordcell --helpThe same release is mirrored to npm:
npm install --global --ignore-scripts @hraness/wordcell@0.21.2
wordcell --helpBun must remain in PATH when npm installs the commands. Exact search and
Markdown graph commands need no account, service, or embedding model. Optional
semantic search, browser capture, and PDF tools have additional prerequisites.
Install the single public Agent Skill into your choice of compatible agent, including Claude Code, Codex, Cursor, or GitHub Copilot:
bunx skills add hraness/wordcell#v0.21.2 --skill wordcellThen ask:
Use Wordcell to find the notes and plans about packages/parser in ./kb.
Open the sources behind the result and explain the recorded decision.
The skill installs instructions, not a running service. It uses an existing
wordcell command and prepares the pinned runtime only when needed. Installing
it does not create a vault or modify your notes. Read the skill.
Suppose a parser must stop retrying after three attempts. Record that constraint in a note, then link the plan that will implement it:
wordcell init kb
wordcell note create notes/parser-contract \
--title "Parser contract" --type concept --tag architecture \
--body "Parser retries stop after three attempts." --root kb
wordcell note create plans/parser-v2 \
--title "Parser v2" --type plan \
--body "The plan implements [[notes/parser-contract|the parser contract]]." \
--root kbThe first wordcell note create command stores ordinary Markdown at
kb/notes/parser-contract.md and assigns its stable document_id. Add the
exact code boundary to that note's frontmatter so path lookup can recover it:
repository_scopes:
- packages/parserCommit the vault with the repository. The Markdown and its Git history are the durable record.
In a later session, start from the code path and inspect each independent signal:
wordcell context packages/parser/src/index.ts --root kb --repo .
wordcell search "why parser retries stop" --root kb --mode exact \
--history --repo .
wordcell backlinks notes/parser-contract --root kb
wordcell history notes/parser-contract --root kb --repo .| Signal | What it recovers |
|---|---|
| Markdown | The current parser constraint in the file you can review and edit. |
| Backlinks | The plan that explicitly links to the constraint. |
| Exact search | The current note matched from its words, without a network request or embedding model. |
| Repository context | Inherited AGENTS.md guides and records scoped to packages/parser. |
| Git history | The commits and bounded co-change evidence associated with the note. |
Together, those views recover the persisted decision, related plan, applicable rules, and provenance needed to resume the work. They do not reconstruct private chat or prove that the note is still correct. Open the returned Markdown and guides before acting on them.
The boundaries stay visible: Markdown and Git are authoritative, backlinks and indexes are replaceable views, and Git work is opt-in. Application code imports neither the vault nor a hosted knowledge service.
| Task | Command | Evidence and effects |
|---|---|---|
| Find a saved decision | wordcell search "parser retries" --root kb --mode exact |
Reads current Markdown; no model or network request. |
| Recover context for code | wordcell context packages/parser/src/index.ts --root kb --repo . |
Returns scoped notes, plans, and inherited AGENTS.md rules. |
| Inspect explicit connections | wordcell backlinks notes/parser-contract --root kb |
Returns notes that link to the decision. |
| Search by meaning | wordcell search "retry policy" --root kb --mode hybrid |
Adds optional local QMD keyword and vector retrieval; model setup is required. |
| Query with graph proofs | wordcell graph query --program scope-route --scope packages/parser --root kb |
Returns bounded results tied to the source revision. Queries do not write a cache. |
| Capture a source | wordcell clip https://example.com/article --output kb/articles |
Reads the selected URL and writes a Markdown bundle with a capture receipt. |
| Capture a PDF | wordcell pdf /absolute/path/to/document.pdf --output kb/articles |
Preserves the original PDF and extracted evidence; Poppler is required. |
| Check the vault | wordcell check --root kb |
Reports structural and attachment problems without editing files. |
Use --json for structured output and wordcell --help for the complete command
surface. Full command reference.
repository/
├── AGENTS.md # rules that govern edits
├── packages/parser/
│ └── AGENTS.md # rules scoped to this code
└── kb/
├── index.md # authored or managed front door
├── articles/ # captured sources and assets
├── notes/ # maintained explanations
└── plans/ # decisions and outcomes
Markdown, YAML frontmatter, explicit wikilinks, and Git hold the record. Open the same files in Obsidian, a text editor, or ordinary file-search tools. Application code does not need to import Wordcell or its vault.
QMD supplies optional local search. Oh, the Hraness
record and memory kernel (source), is embedded
as a derived graph authority behind an engine-neutral port: only an explicit
wordcell graph rebuild --root kb writes .wordcell/oh.sqlite, the file stays
ignored and rebuildable, and nothing flows from the projection back into notes.
Backlinks and typed relationships come from authored links. Percolation
suggests connections for review and does not add inferred edges to notes.
Graph proofs explain a supported derivation from a specific source revision. They do not prove that a note is true or that a missing relationship cannot exist. Graph queries and proof limits.
Add the same immutable release to a Bun project:
bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.2/hraness-wordcell-0.21.2.tgzThe SDK provides read-only vault sessions, metadata queries, search, graph proofs, Git context, and composable workflows. A session owns one snapshot; reopen it after Markdown changes. SDK and workflow examples show the public imports and lifecycle.
- Structural queries and exact search read local files. Optional semantic search downloads its model on first use and runs locally.
- URL capture contacts the requested source. Signed-in capture uses only explicitly selected browser state. Review the security policy before using it with private sources.
- An agent that reads the vault follows its own provider and data-handling settings. Keep private records out of public repositories and outputs.
- Git history is opt-in. Saved notes preserve recorded context; Wordcell does not reconstruct unsaved conversations or silently record every agent action.
| Read next | Purpose |
|---|---|
| Agent workflow | Set up, query, maintain, and revise repository memory. |
| Installation and command reference | Exact interfaces, SDK imports, optional adapters, and troubleshooting prerequisites. |
| Web capture and PDF capture | Save sources with provenance, assets, and explicit completeness limits. |
| Graph guide | Named queries, proofs, revisions, resource limits, and cache recovery. |
| Portfolio federation | Search only selected, authorized vaults. |
| Design and memory rationale | File contracts, design choices, and evaluation context. |
| Release verification | Verify archive identity, signatures, and provenance. |
Alternative installs and optional capabilities.
Existing kb/, index.md, kb:// identifiers, and Markdown formats remain
compatible. Vault format reference.
Capture commands and dependencies.
Installation and runtime contract.
The same skill is included at node_modules/@hraness/wordcell/skills/wordcell/.
Version 0.21 adds Oh graph queries and proofs. The deprecated kb command was
removed at this boundary; use wordcell. Existing vaults need no migration.
All release notes and upgrade instructions.
Run bun run check for source, architecture, package installation, types, and
native-helper validation. The site has its own bun run check under site/.
See Contributing, Security, and the MIT License.
Install Wordcell from GitHub Releases · Wordcell source on GitHub · Wordcell overview