Wordcell
Install Wordcell
Theme
Appearance

For coding agents

Keep the rules in AGENTS.md and the reasons in the vault.

Keep a Markdown knowledge base beside your repository. Save decisions, tie them to code paths, and let the next agent look them up from the file it edits.

Install WordcellRead the agent workflow

Latest release: v0.24.0 · Free under the MIT license · Exact search needs no account or model.

Get started

Install and connect your agent

You need Bun 1.3.14 or newer and Git. These steps install Wordcell v0.24.0.

1Install the CLI
bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.24.0/hraness-wordcell-0.24.0.tgz
wordcell --help
2Teach your agent the commands
bunx skills add hraness/wordcell#v0.24.0 --skill wordcell

The skill gives a compatible agent instructions; it does not run a service. Set up repository memory step by step. See how this release was built and verified.

The workflow

The loop, end to end

Every step writes or reads plain Markdown. The agent pulls the record when the task needs it.

  1. Initialize the vaultwordcell init kb

    Creates a folder of Markdown that any editor can read.

  2. Save the decisionwordcell note create notes/parser-contract --title "Parser contract" --type concept --root kb

    One file holds the constraint; frontmatter makes it queryable.

  3. Scope it to the coderepository_scopes: [packages/parser]

    The scope lives in the note's own frontmatter, so there is no central table to update.

  4. Let the agent pull contextwordcell context packages/parser/src/index.ts --root kb --repo .

    Returns scoped notes, related plans, and inherited AGENTS.md rules.

  5. Look up the historywordcell history notes/parser-contract --root kb --repo .

    Lists the commits that changed the note.

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 .

Start from the file you are changing. context lists the notes and AGENTS.md guides that apply to it, backlinks shows what links to the note, and history lists the commits that changed it. They print paths and short summaries, and the agent opens a full note when it needs one.

In the vault

Context an agent can inspect

Search returns a limited set of results, each with a source the agent can open.

  1. Context for a code path

    A note lists the repository paths it is about. Starting from the file you are changing, one command returns the notes and plans tied to it and the AGENTS.md guides that apply.

  2. Rules in AGENTS.md, reasons in the vault

    AGENTS.md holds the rules an agent loads on every task. The vault holds the history, evidence, and reasoning behind those rules, and the agent reads it when a task calls for it.

  3. Commits behind the note

    A vault committed with the repository keeps its history. List the commits behind a decision when you need to know how it changed.

  4. Plans linked to their reasons

    A plan wikilinks to the constraint it implements. Backlinks on the decision recover the work that depends on it.

  5. Evidence saved with the work

    Clip the issue, discussion, or PDF that motivated a decision. The capture keeps a record of where and how it was saved, beside the note.

  6. Sessions for your own tools

    The TypeScript SDK opens a read-only snapshot of a vault. Build agent or CI workflows on top of it.

Measured

A fifth of the context, measured

Packed snippets carry what matched, not the whole note. Across four queries on a seven-note public vault, snippets used 80% fewer UTF-8 bytes than the same notes in full.

12,126 bytesPacked snippets

60,584 bytesThe same notes in full

Payload size, not accuracy; savings depend on your notes and query. Method and raw report.

Oh backs Wordcell’s graph queries and source proofs. Markdown and Git remain authoritative; Wordcell search has its own retrieval path and evidence. How the integration works · Wordcell’s retrieval study.

Interfaces

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.

CLI

Search, context, history, and validation from a terminal or script.

wordcell context packages/parser/src/index.ts \
  --root kb --repo .

TypeScript SDK

Open a read-only snapshot of a vault from TypeScript and run searches and workflows against it.

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

Inspect the packaged skill

Trust

What Wordcell shares

Wordcell records only what you save as notes, and its hosted features stay off until you use them.

Data

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 is off by default. When you turn it on, it sends TypeSafe your query and, for up to 25 candidates, each note's identifier, title, path, and up to 512 bytes of its snippet.
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.

FAQ

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.

Install WordcellRead the agent workflow

Latest release: v0.24.0 · Free under the MIT license · Exact search needs no account or model.