A local knowledge base for coding agents. Save decisions in Markdown and recover the context behind your code. Give the next session only the context it needs.
Your files stay yours: read them in Obsidian or any editor, review changes in Git, and rebuild every index from the Markdown. Exact search and graph queries run on your machine with no account or model. Web capture, hosted agents, and optional remote reranking have separate privacy boundaries.
Documentation · Comparisons · Measured evidence · Changelog
- Keep decisions with the work. Link a plan to the notes that explain it, attach those notes to a code path, and recover their Git history on request. Only context you save becomes part of the record.
- Read what matters. Start with a code path, search result, or linked note. Get a limited set of summaries and open the sources you need, instead of loading the whole vault into an agent conversation.
- Keep control of your knowledge. Markdown and Git are the source of truth. Use local search, export selected notes as a static site, and keep using the files even without Wordcell.
Plain Markdown may be enough for a small set of notes. QMD is a good fit for local document retrieval and also supplies Wordcell's optional semantic search. Wordcell adds a connected workflow for repository context, authored relationships, Git evidence, and selective publishing. Compare the tradeoffs.
Bun 1.3.14 or newer and Git are required. The CLI and TypeScript SDK run with Bun. Install the versioned GitHub archive:
bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.1/hraness-wordcell-0.22.1.tgz
wordcell --helpPrefer npm? The same release is mirrored there:
npm install --global --ignore-scripts @hraness/wordcell@0.22.1
wordcell --helpKeep Bun in PATH for either installation. If your shell cannot find wordcell,
add your package manager's global executable directory to PATH and reopen the
terminal. Optional semantic search, browser capture, and PDF tools have
additional prerequisites.
Run this from a directory where you want a new kb/ folder. It creates one
Markdown note and finds it without downloading a model or contacting a service:
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 search "parser retries" --root kb --mode exactThe result includes notes/parser-contract and the saved retry constraint.
Open kb/notes/parser-contract.md to see the ordinary Markdown file. Wordcell
adds a stable document_id in its frontmatter; you can edit the prose normally.
Already have Markdown or an Obsidian vault? In v0.22.0 or newer, search
the existing folder without initialization or an index.md file:
wordcell search "a phrase from your notes" --root /path/to/your/vault --mode exactReplace the path and phrase with your own. You don't need to initialize, convert, or move the existing files to search them.
After trying the CLI, install the public Agent Skill into a compatible agent, such as Claude Code, Codex, Cursor, or GitHub Copilot:
bunx skills add hraness/wordcell#v0.22.1 --skill wordcellThen ask:
Use Wordcell to search for "parser retries" in ./kb using exact mode.
Read the matching note and explain the saved constraint.
The skill installs instructions, not a service. Installation does not create a vault, modify your notes, or grant an agent permission to access other accounts. The agent still follows its own provider and data-handling settings. Inspect the skill.
Link a plan to the decision you saved:
wordcell note create plans/parser-v2 \
--title "Parser v2" --type plan \
--body "The plan implements [[notes/parser-contract|the parser contract]]." \
--root kb
wordcell backlinks notes/parser-contract --root kbThe backlink result includes plans/parser-v2, so a later session can find the
work that depends on the constraint.
For code-path lookup, add this field inside the existing frontmatter of
kb/notes/parser-contract.md:
repository_scopes:
- packages/parserFrom your repository root, use an actual path under that scope and inspect the
returned notes and inherited AGENTS.md guides:
wordcell context packages/parser/src/index.ts --root kb --repo .Commit the vault with your repository to preserve its history, then use
wordcell history notes/parser-contract --root kb --repo . to inspect the
commits behind the note. History is optional and requires recorded Git commits.
These views recover saved decisions, related work, rules, and provenance. They do not reconstruct private chat or prove that the note is still correct. Open the returned Markdown and guides before acting on them.
wordcell search "why releases use immutable archives" --root kb --mode exact \
--rerank typesafe --rerank-limit 25 --limit 5 --jsonThis optional hosted lane uses TypeSafe's pinned jev-1.13.0 model. It sends
bounded query and note snippets to the provider, needs a private local
credential, and incurs provider charges. Exact identities remain first; a
provider failure retains the baseline order with a diagnostic. See the
setup, SDK examples, measured results, and limits.
| 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. |
| Publish selected notes | wordcell publish --root kb --out site/ --include notes/parser-contract --dry-run --json |
Previews a static site selection locally; remove --dry-run to build it. |
| Preview a site | wordcell serve --root site --port 8080 |
Serves a published site on a loopback static file server with the emitted 404.html fallback. |
Use --json for structured output and wordcell --help for the complete command
surface. Full command reference.
Preview the decision and plan from the example before writing an output folder:
wordcell publish --root kb --out site \
--include notes/parser-contract --include plans/parser-v2 --dry-run --jsonReview the selection, then build and preview it:
wordcell publish --root kb --out site \
--include notes/parser-contract --include plans/parser-v2
wordcell serve --root site --port 8080Open http://127.0.0.1:8080. You get readable pages, linked notes, and search
that runs in the browser. Upload the site/ folder to your chosen static host
when you want to share it; publish itself never uploads anything.
For a repeatable slice, use path patterns or combine folders, tags, metadata, code scopes, and linked neighborhoods:
wordcell publish --root kb --out site-notes \
--include-glob 'notes/**/*.md' --exclude-glob '**/draft-*' --dry-run --jsonPreview reports show up to 20 selected IDs by default, with a total count and
selection digest. They keep note bodies out of the agent's context. Use
--list-limit to adjust that preview without changing what gets published. publish: false excludes a note, but selected
prose and attachments still need review before sharing: selection is not secret
redaction. Selection recipes and hosting guide.
In a four-query example over a seven-note public vault, packed search snippets used 80% fewer UTF-8 bytes than passing the same matching notes in full: 12,126 versus 60,584 bytes. This measures context payload size, not tokenizer counts, answer quality, latency, or a win over another search tool.
In a separate public SciFact study, optional hosted Jev reranking placed a judged relevant result first for 161 of 300 queries, versus 101 with Wordcell exact search alone. It sends bounded context to a paid provider; this is evidence on scientific abstracts, not a comparison with QMD or a guarantee for repository notes. Results and limits.
Wordcell's benefit is selecting relevant context and keeping its sources inspectable. Local ownership is also available in other tools, and Wordcell does not claim to beat QMD's retrieval quality or every Markdown workflow.
Measured evidence shows a reproducible public-vault example, with the inputs, output sizes, and limits beside each result. The comparison guide covers Markdown alone, QMD, Basic Memory, Obsidian, and static publishing tools using their own documentation. Choose the smallest workflow that meets your needs.
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.22.1/hraness-wordcell-0.22.1.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. Optional Jev reranking sends the query and bounded candidate context to a remote provider; it is off by default.
- 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. |
| Publish selected notes | Preview a slice, build a static site, and choose how to host it. |
| 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.22 adds selective static publishing and local preview. Choose notes,
folders, path patterns, metadata, or linked neighborhoods, then inspect a
bounded selection report before building. Existing vaults need no migration.
The deprecated kb command was removed in 0.21.0; use wordcell.
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
wordcell support shows optional development support for Wordcell. Features stay
free and no account is required. Accounts presents current terms; the person
confirms any payment in their browser. Wordcell has no product newsletter and
does not look up an email address for support.
After useful standalone work, agents can receive a discovery record on stderr.
Read wordcell support protocol --json for the shared closeout procedure.
Help, diagnostics, evaluation, SDK calls and nested commands stay quiet.
HRANESS_SUPPORT=off or HRANESS_SUPPORT_AUDIENCE=off suppresses incidental
invitations. Explicit human terminal rendering requires
HRANESS_SUPPORT_AUDIENCE=human; the default audience is an agent, including in
a pseudo-terminal.
wordcell support dismiss disables invitations across participating tools on
this machine. snooze pauses them for thirty days, enable restores them, and
status --json shows their separate local preferences. These commands do not
change a vault, sign up or pay. Acknowledged invitations share a seven-day
cooldown; discovery itself does not consume it.