Wordcell

Install the Agent Skill

A local Markdown knowledge base with superpowers. Save decisions, sources, and plans as files you own, then recover them through exact and semantic search, typed relationships, backlinks, and Git history. Coding agents get the context behind your code, and the same record holds everything else you need to remember.

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

Why Wordcell

• Keep what you learn in files you own. Write decisions, sources, and plans in Markdown. Obsidian, Git, and Wordcell read the same record, and every index rebuilds from the files.
• Find it by words or by meaning. Exact search needs no model or account. Optional local semantic search joins each match to current metadata, links, and history instead of returning isolated text.
• Author the connections. Wikilinks and typed relationships turn notes into a queryable ontology. Backlinks, bounded graph proofs, and percolation suggestions recover them without injecting edges you did not write.
• Ground coding agents in context. Scope notes to repository paths, recover the commits behind a note, and give the next session only what it needs. Only context you save becomes part of the record.

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.

Install

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.0/hraness-wordcell-0.22.0.tgz
wordcell --help

Prefer npm? The same release is mirrored there:

npm install --global --ignore-scripts @hraness/wordcell@0.22.0
wordcell --help

Keep 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.

Keep one decision available to the next session

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 exact

The 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 exact

Replace the path and phrase with your own. You don't need to initialize, convert, or move the existing files to search them.

Use with a coding agent

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.0 --skill wordcell

Then 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.

Recover the stopped session

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 kb

The 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/parser

From 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.

Rerank a search window

wordcell search "why releases use immutable archives" --root kb --mode exact \
  --rerank typesafe --rerank-limit 25 --limit 5 --json

This 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.

What you can do

Use --json for structured output and wordcell --help for the complete command surface. Full command reference.

Publish a selected part of your vault

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 --json

Review 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 8080

Open 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 --json

Preview 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.

Evidence and comparisons

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.

How the files fit together

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.

Build with the TypeScript SDK

Add the same immutable release to a Bun project:

bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz

The 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.

Privacy and boundaries

• 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.

Documentation

The documentation follows the Diataxis split: a tutorial to learn the loop, how-to guides for tasks, reference for exact interfaces, and explanation for the design. Browse it on the documentation index.

Installation reference

Alternative installs and optional capabilities.

The kb vault format

Existing kb/, index.md, kb:// identifiers, and Markdown formats remain compatible. Vault format reference.

Command surface

Complete CLI reference.

Capture reference

Capture commands and dependencies.

Graph reference

Graph and SDK interfaces.

Agent skills

Installation and runtime contract. The same skill is included at node_modules/@hraness/wordcell/skills/wordcell/.

Release notes

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.

Contributing

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

Optional development support

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.