Wordcell

Wordcell is a Markdown knowledge base and local MCP memory server for coding
agents such as Claude Code, Codex, and Cursor. It keeps decisions, plans, and
sources as Markdown files beside your code, and agents find them by exact
words, by meaning with an optional local model, or from the file they are
about to change.

A new coding-agent session can read your code, but not the decisions that
stayed in the last session's chat. Wordcell keeps those decisions as Markdown
files beside the repository, with the plans that depend on them and the web
pages and PDFs that informed them. Tie a note to the paths it explains, and an
agent about to change that code runs one command to get the notes and plans
for that path. Exact search, backlinks, and Git history run on your machine
with no account or model, and every index rebuilds from files you can read in
any editor. Wordcell is free and open source.

Web capture, optional hosted reranking, and your agent's provider reach other
services; Privacy and boundaries says what each one
sends.

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 graph you can query. Backlinks and graph queries use only what you wrote,
  and wordcell percolate suggests missing links for you to review without
  writing them into your notes.
• Give coding agents the reasons behind the code. Tie notes to repository
  paths, list the commits behind a note, and let the next session start from
  the notes for the file it is changing. 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.

Wordcell keeps the record in Markdown files you own, rebuilds every index from those files, and lets the next session start from the notes for the file it is changing: the design every Hraness project shares. The thread through hraness follows that design across the projects, and the ALGAL vision states the bet behind it.

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.24.0/hraness-wordcell-0.24.0.tgz
wordcell --help

Prefer npm? The same release is mirrored there:

npm install --global --ignore-scripts @hraness/[email protected]
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.24.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.

Use a vault as agent memory

wordcell mcp --root kb serves a vault to a local MCP client, such as Claude
Code, Claude Desktop, Cursor, or Codex, over standard input and output. The
client can search, list, and read notes, follow links, create notes, update a
note body at a known revision, and add typed relations. --read-only removes
the write tools. Connect a client
shows the setup for each host.

With the Agent Skill, ask your agent to save the session. It writes a dated
session note, links it to the notes it changed, and keeps a profile note for
you or your project. Wordcell extracts no facts and writes no note on its own.
Session memory and profiles.

To move from Supermemory, wordcell import supermemory turns saved Supermemory
API responses into Markdown notes. The migration guide
covers export, import, and what does not transfer, and the
Supermemory comparison lists when to
choose Supermemory instead. Sync with Git
keeps one vault current on several machines.

Evidence and comparisons

On eight questions sealed before the passage selector was finished,
wordcell search --selected-passage returned an excerpt holding the labeled
answer for 6 of 8, versus 1 of 8 for the older search snippets, at the
same 512-byte limit and from the same retrieved notes. It runs locally with no
model. The corpus is small and consists of Wordcell's own notes; containing the
answer is not the same as an agent answering correctly.
Method, raw results, and reproduction.

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, static publishing tools,
Supermemory, Mem0, and Zep using their own documentation. Choose the smallest
workflow that meets your needs.

The benchmarks page shows the excerpt, payload,
and SciFact results beside the published results of Oh, the embedded memory
framework, each with its source data and limits. On all 500 LongMemEval-S
questions, Oh semantic retrieval scored 88.87% and BM25 86.13% with the same
reader and budget; on the measure Oh named before the run, its interval does
not rule out a tie. Oh's scores measure its own memory-retrieval path, not a
Wordcell vault.

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.

Wordcell is the Markdown knowledge base. Oh is the
embedded memory framework that backs its named graph queries and source proofs.
Markdown and Git remain authoritative. Query the graph immediately without an
Oh account, service, or persisted database:

wordcell graph query --program backlinks --note notes/parser-contract --root kb --json

The result traces each returned link to its source note and revision. 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.

Wordcell search combines its own exact matching with optional QMD local search
and optional hosted Jev reranking. Oh also offers memory retrieval for applications;
its conversation-memory benchmark scores measure that separate path. They do not
establish Wordcell's retrieval or answer quality. How the integration works.

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.24.0/hraness-wordcell-0.24.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.