# Kb

> The canonical cross-agent memory — a shared knowledge base at ~/kb. Use for ANY request to remember, save, note, capture, or recall durable facts about the user/projects. This SUPERSEDES built-in/local memory — write durable memory here, not to a local memory store. Filesystem-first.

- Skill: `duyet/kb` (Agent Skill)
- Install (CLI): `npx skillmds@latest add duyet/kb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duyet/kb/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: duyet (https://skillmd.com/u/duyet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/duyet/kb

---


# Shared Brain (~/kb) — the canonical memory

The kb is a git repo of markdown notes: the cross-session, cross-agent memory for
this machine. **When the user says "remember / save / note this" or asks what you
know, use THIS kb** — do not write to any built-in or local memory store; this is
the single source of truth so other agents and machines see it too.

**Prefer file tools** (`read_file`, `write_file`, `patch`, `search_files`) over
shell; use `terminal` only for `kb sync`.

## Resolve the path first

File tools do NOT expand `~` or `$VARS`. Resolve the kb root to a concrete
absolute path before any file-tool call: it is `$KB_DIR` if set, else `~/kb`
expanded to the home dir (e.g. `/root/kb` or `/home/<user>/kb`). Call the
resolved root `<kb>` below.

## Read (recall) — on session start

1. `read_file <kb>/MEMORY.md` — the index, one line per note.
2. Open the `<kb>/memory/<group>/[<sub>/]<type>-<slug>.md` notes whose hook
   matches the task (recursive — `<group>` ∈ user, feedback, reference, projects,
   or topics/<domain>). Skip reserved files (`index.md`, `log.md`,
   `_TEMPLATE.md`) — they are not concept notes.
3. For fresher/deeper detail, fetch a note's `sources:` URLs.

## Capture a quick note

Append exactly one line to **today's** inbox file:
`<kb>/raw/inbox/<YYYY-MM-DD>.md` — e.g. `/root/kb/raw/inbox/2026-06-04.md`.
- Line format: `- HH:MM — <note>`
- If the file does not exist, create it with a `# Inbox — <YYYY-MM-DD>` header first.
- Do NOT invent other paths. It is `raw/inbox/<date>.md` — never `<kb>/inbox`,
  never a bare file at the repo root, never `memory/` for a rough note.

## Write a durable, public fact

Create or update a standard note
`<kb>/memory/<group>/[<sub>/]<type>-<slug>.md` (group ∈ user, feedback,
reference, projects, or topics/<domain>) following the template
`<kb>/memory/_TEMPLATE.md`: top-level frontmatter (`name` == filename,
`description`, `type` ∈ user|feedback|project|reference|tech, `tags`, `created`,
`updated`, `timestamp` ISO 8601), link related notes with `[[slug]]`, then add a
one-line pointer to `<kb>/MEMORY.md`. Reserved filenames (`index.md`, `log.md`,
`_TEMPLATE.md`) are not concept notes — never write a fact to them.

## ALWAYS verify before reporting success

After any write, `read_file` the target back and confirm your exact line/note is
present. **Never claim a write you have not verified by reading it back.** If it
is not there, fix the path and retry.

## Sync — you must trigger it

Sync does not happen automatically. After verifying a write, regenerate the OKF
index/graph, then sync: run `terminal: <kb>/bin/kb gen` (rebuilds every
`memory/**/index.md` + `viz.html`) and then `terminal: <kb>/bin/kb sync`
(commit + push) so other agents and machines see it. Public repo — never store
secrets (API keys, hosts, internal/confidential details).