CLI
Search, capture, link, and validate from a terminal or a script.
wordcell search "why parser retries stop" \
--root kb --mode exact --history --repo .A knowledge base for coding agents
Wordcell
Memory your coding agents can open, search, and trust
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.
Free and MIT licensed. Bun 1.3.14 or newer, plain Markdown, no account. First Wordcell release in preparation.
$ wordcell note create notes/parser-contract \
--title "Parser contract" --type concept --tag architecture \
--body "Parser retries stop after three attempts." --root kb
$ wordcell context packages/parser/src/index.ts --root kb --repo .
$ wordcell backlinks notes/parser-contract --root kb
$ wordcell history notes/parser-contract --root kb --repo .The model
Plain files, derived views.
A vault is Markdown under version control. Wordcell adds the write path and the bounded read paths an agent needs, and keeps every index replaceable.
Notes
Ordinary Markdown with frontmatter. A stable document id, tags, and typed relationships live in the file, so Obsidian, grep, and Git all read the same record.
Backlinks and graph views
Derived at read time from wikilinks and typed relationships. Wordcell never writes reciprocal or inferred edges into your notes.
Search lanes
Exact metadata filters, local full-text, and optional local embeddings stay separate evidence. Results join back to the current file, never to a stale index.
Git provenance
History and co-change come from your repository's own log, on request, as context rather than a silent relevance boost.
Capture
Clip a page or a PDF into the vault with its source metadata, assets, and a capture receipt an agent can verify later.
Repository scopes
Route a code path to the notes, plans, and decisions that own it, so the next session starts from the right context.
Interfaces
One vault, three interfaces.
The CLI, the SDK, and the packaged skill read and write the same files. There is no agent-only path behind the convenient one.
TypeScript SDK
Open a read-only session over one vault scan and compose bounded workflows.
import { openKnowledgeBase } from "@hraness/wordcell/sdk";
const session = await openKnowledgeBase({ root: "kb" });
const hits = await session.search({ query: "parser contract", mode: "exact" });Agent Skill
Teach a coding agent the vault rituals through skills.sh.
The first Wordcell skill release is in preparation.
Boundaries
What Wordcell will not do.
Wordcell derives views from your files and refuses to become a second source of truth.
Guarantees
Small enough to trust.
These rules are enforced by the command surface and its tests, not by convention.
- Markdown is authoritative
- Catalogs, backlinks, graph reports, semantic indexes, and repository context are derived and disposable. Nothing you commit depends on a database.
- Bounded and inspectable
- Every command returns sorted, bounded results with the evidence behind them. Search never becomes graph authority, and percolation only proposes.
- Headless by design
- A CLI, a TypeScript SDK, and a packaged Agent Skill operate the same vault. Application code never has to import the knowledge system.
First Wordcell release in preparation
Install and start a vault.
Wordcell is being prepared for its first release under the new name. Check published releases or read the documentation.
Questions
Before you install.
Where does my knowledge live?
In a directory of Markdown files, conventionally kb/, committed beside your code. Wordcell reads and writes those files; it keeps no server, account, or hidden state.
What changed with the Wordcell name?
Only the product identity. The package is @hraness/wordcell and the command is wordcell, with kb kept as a deprecated alias through 0.20.x. The vault format keeps its kb names, so existing vaults need no migration.
Do I need an embedding model?
No. Exact and keyword search work without one. Hybrid and semantic modes use a pinned local model through the optional QMD dependency, and the index is rebuildable from Markdown.
How do agents use it?
Install the wordcell Agent Skill through skills.sh. It teaches Codex, Claude Code, and compatible agents to search, capture, plan, percolate, refresh, and validate a vault with the installed command.
How is it published?
Each release is an immutable GitHub Release with a packing receipt, checksums, and signed provenance. The same archive bytes are published to npm from the tag workflow through OIDC trusted publishing.
Who made it?
Ben Guo, a musician and builder, formerly a founder and engineering leader at companies including Venmo and Stripe, now building from Puerto Rico. Wordcell is published by Hraness under the MIT license.
The maker
Built by Ben Guo
Wordcell is built by Ben Guo, a musician and builder, formerly a founder and engineering leader at companies including Venmo and Stripe, now building from Puerto Rico. It is published by Hraness under the MIT license.
Give the next session what this one learned.
Install the CLI, start one vault beside your code, and let your agents record what they should not have to rediscover.
Free and MIT licensed. Bun 1.3.14 or newer, plain Markdown, no account. First Wordcell release in preparation.