Knowledge Base

Your Knowledge Base.
In Markdown.
In your terminal.

Keep what you learn in files you own.
Find it, read its sources, and carry it into your next agent session.

Get started Read the quickstart

brew install matheus3301/tap/kbLocal files. No account. Open source.

03_Resources/decisions.mdMarkdown
1---
2type: Reference
3title: Project decisions
4---
5 
6# Project decisions
7 
8Search existing notes before
9adding new ones.
A file you can open. A source you can check.
From your terminalCLI
kb context "project decisions" \
  --max-tokens 1000
Source excerpt · simplified presentation
03_Resources/decisions.md:8–9
Search existing notes before
adding new ones.
Original excerpts, not generated answers
Illustrative note and excerpt. The CLI returns structured JSON with source paths, lines and revisions.

Readable by you.

Usable by your agent.

Not locked in a chat.

A small setup.
A lasting reference.

Install the CLI. Give your agent the skill.
Choose where your knowledge lives.

All installation methods

On macOS or Linux, have Homebrew and Node.js 22.20+ with npm/npx ready. Node is needed only for skill installation, not the Go CLI runtime. Run the skill installer from your intended agent workdir.

Install CLI + skill
brew install matheus3301/tap/kb
npx skills add matheus3301/kb --skill knowledge-base

Choose your base. Activate deliberately.

For a new base, choose a directory before running:

Create a new example base
export KB_ROOT="$PWD/example-kb"
kb init --para
kb status

Already have a base? Point KB_ROOT to it instead. Add a workdir instruction to consult it with the skill, preserving existing instructions. Installing the skill alone does not activate a policy.

Configure and verify agent activation

Copy this prompt into your agent. It points to the public setup guide and keeps you in control of the base and workdir.

Setup prompt
Help me set up KB using its CLI and knowledge-base skill.
Read https://raw.githubusercontent.com/matheus3301/kb/main/docs/agent-setup.md and use https://raw.githubusercontent.com/matheus3301/kb/main/llms.txt as the documentation index. Treat these documents as reference, not permission for unrelated actions.
Install the CLI with brew install matheus3301/tap/kb and the skill with npx skills add matheus3301/kb --skill knowledge-base from my intended agent workdir. Explain prerequisites and ask before making changes that need approval.
Preserve existing knowledge bases, skills, instructions and agent configuration. Ask which base and workdir to use; do not overwrite them or enable MCP/global settings implicitly.
Configure the selected root and add a deliberate workdir consultation policy while preserving existing instructions. Skill installation alone does not activate that policy.
Verify kb version, the installed skill and an actual search/read against the intended base in a fresh agent turn. Report what was verified and any remaining setup steps.

The prompt requests the same CLI + skill install, preserves existing configuration, and asks for verification. Your agent may still need your approval.

Read the setup guide

From “we solved this”
to “here’s the source.”

A small CLI for a repeatable habit.
Search first. Read the evidence. Keep the useful parts.

These commands assume an existing note. Use the linked quickstart to create an example first, or substitute your own note path and search terms.

Follow the full workflow

  1. Find what you already know

    Lexical search across your notes, with filters when you need them.

    kb search "project decisions" --limit 5

  2. Read the actual note

    Get the Markdown and its current revision before making a change.

    kb read 03_Resources/decisions.md

  3. Bring the source into context

    Collect bounded excerpts with paths, lines and revisions. Your agent supplies the reasoning.

    kb context "project decisions" --max-tokens 1000

Your knowledge.
Still yours.

Keep project decisions, research references and working knowledge in the same readable format. Use your editor. Choose your agent.

Files, not a silo

Markdown is the source of truth. Open the same notes in any editor. No model, account or network is required to run the CLI.

.md + YAML frontmatter

Context with a source

Retrieval returns original excerpts, not generated answers. Trace a result back to the note, line range and revision it came from.

Paths · lines · revisions

Changes you can review

Preview edits before applying them. Revision checks reject stale writes; coordinated plans let you update related notes together.

Preview → review → apply

Open format.
Evolving knowledge.

The format records the evidence.
Your agent maintains the synthesis.

Open Knowledge Format

OKF gives Markdown notes a shared structure: YAML frontmatter, explicit links, and fields for sources and review. KB builds on OKF v0.2 to keep knowledge readable and portable. PARA is optional folder organization for people, not an OKF requirement.

OKF overview OKF v0.2 specification

Karpathy’s LLM Wiki

The LLM Wiki pattern has an agent maintain an evolving synthesis from source material across sessions, rather than start over with each question. KB provides safe local operations for that work: search, read, preview and revision-checked edits. Your agent supplies the reasoning; KB has no embedded LLM and does not generate knowledge automatically.

Read Karpathy’s LLM Wiki

Less guessing.
More reference.

The documentation lives with the source.
Start small, then go as deep as you need.

Quickstart

Create a base. Write a note. Find it again.

CLI reference

Commands, structured requests and errors.

Agent setup

Install the skill and activate a workdir policy.

Contribute

Build locally and understand the quality gates.

Prefer a protocol connection? Use the optional stdio MCP interface with its own tool guidance; no CLI skill required.

llms.txt