CLI
Search, context, history, and validation from a terminal or script.
wordcell context packages/parser/src/index.ts \
--root kb --repo .Give coding agents the decisions behind your code
A local Markdown knowledge base beside your repository. Save decisions, scope them to code paths, and give the next session only the context it needs.
Free and MIT licensed. Local Markdown. No account or model for exact search. Current verified release v0.22.0.
$ 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 .Path-scoped notes, their dependents, and their provenance. Nothing else enters the conversation.
Install and connect your agent
Current verified release · v0.22.0
bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz
wordcell --helpbunx skills add hraness/wordcell#v0.22.0 --skill wordcellPublic release verification. The skill installs instructions for a compatible agent, not a service. Set up repository memory step by step.
The loop, end to end
Every step writes or reads plain Markdown. The agent pulls the record when the task needs it.
- Initialize the vault
wordcell init kbCreates a folder of Markdown that any editor can read.
- Save the decision
wordcell note create notes/parser-contract --type concept --root kbOne file holds the constraint; frontmatter makes it queryable.
- Scope it to the code
repository_scopes: [packages/parser]A frontmatter field on the note, not a central database row.
- Let the agent pull context
wordcell context packages/parser/src/index.ts --root kb --repo .Returns scoped notes, related plans, and inherited AGENTS.md rules.
- Recover the history
wordcell history notes/parser-contract --root kb --repo .The commits behind the note, when provenance matters.
Context an agent can inspect
Search returns bounded results with sources an agent can open, not a dump of the whole vault.
Context for a code path
A note declares the repository paths it is about. Starting from the file you are changing returns its scoped notes, plans, and the AGENTS.md guides that govern the edit.
Rules and rationale, separated
AGENTS.md stays the normative, always-loaded rule file. The vault holds the pull-based history, evidence, and reasoning behind those rules.
Commits behind the note
A vault committed with the repository keeps its history. Inspect the commits behind a decision when provenance matters.
Plans linked to their reasons
A plan wikilinks to the constraint it implements. Backlinks on the decision recover the work that depends on it.
Evidence saved with the work
Clip the issue, discussion, or PDF that motivated a decision. The capture keeps its provenance receipt beside the note.
Sessions for your own tools
The TypeScript SDK opens a read-only snapshot over one vault scan. Compose bounded workflows for your agent or CI.
Measured context, stated limits
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 tokens, answer quality, or a win over another search tool. Method and raw report.
The graph core is Oh, the Hraness memory kernel. Its completed memory studies reached 89.8% answer accuracy on LongMemEval-S and 84.4% on LoCoMo, descriptive in-sample scores with stated limits. Results and method.
CLI, skill, or SDK
The CLI is the smallest commitment. The skill teaches an agent the same commands; the SDK embeds them in your tools.
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" });Agent Skill
Give your agent instructions for finding and maintaining saved context.
bunx skills add hraness/wordcell#v0.22.0 --skill wordcellBoundaries the agent respects
Only saved context becomes part of the record, and external lanes stay explicit.
What reaches the model
Know what stays on your machine and what a connected agent can see.
- Nothing is recorded for you
- Wordcell stores only what you save as notes. It does not reconstruct private chat or silently log agent actions.
- Local retrieval by default
- Exact search, graph queries, and optional local semantic search run on your machine. Optional hosted reranking sends a bounded window and is off by default.
- The agent keeps its own rules
- A connected agent still follows its provider's data-handling settings. Keep private records out of public repositories and outputs.
Before you connect an agent
How does the agent know what to read?
wordcell context starts from a repository path and returns only the notes, plans, and rules scoped to it. Exact and hybrid search cover the cases where you know the words. The agent opens full notes only for the results it needs.
What does the Agent Skill do?
It installs instructions for a compatible agent, such as Claude Code, Codex, Cursor, or GitHub Copilot. It does not start a service, create a vault, or grant access to external accounts.
Can I use it on an existing vault or repository?
Yes. Exact search reads any existing Markdown folder without initialization. Repository scopes are optional frontmatter you add where the context is worth recovering.
Does it record my agent sessions?
No. Wordcell stores only what you save as notes. It does not reconstruct private chat or silently record agent actions; Git history is opt-in and covers recorded commits.
Give the next session what this one learned
Save one decision beside the code, then let the agent find it.
Free and MIT licensed. Local Markdown. No account or model for exact search. Current verified release v0.22.0.