convez.ai
AgenteProdutividadeAvançado
JustinBeaudry

KB - Cofre de Memória Persistente

JustinBeaudry/kb

Cofre Markdown inteligente que persiste conhecimento entre sessões do Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin de memória persistente para Claude Code que mantém um cofre Markdown estruturado entre sessões. Implementa padrão de wiki inteligente com ingestão de fontes, consultas com citações e linting automático do conhecimento acumulado.

Instalação

$npx convez-ai JustinBeaudry/kb

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 semanas
Versão
0.7.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter base de conhecimento técnico estruturada durante desenvolvimento
  • Acumular decisões arquiteturais e padrões de projeto entre sessões
  • Consultar histórico de aprendizados com rastreamento de fontes
  • Extrair conhecimento de sessões anteriores para wiki permanente

Veredito

Solução robusta para times que precisam de memória persistente estruturada em projetos de código. Arquitetura bem pensada com separação entre conhecimento curado e bruto, mas exige comprometimento com organização e TypeScript/Bun para funcionar plenamente.

README

A tradução para o português deste README ainda está na fila.

KB

A persistent memory plugin for Claude Code. Markdown vault maintained by your agent across sessions. Based on Karpathy's LLM Wiki pattern.

What it does

  • SessionStart hook injects vault context — a compact pointer by default (lazy mode), or the working set, index, and recent session summaries in eager mode
  • Stop hook writes a small session manifest when you finish working
  • PostCompact hook re-injects vault context after compaction (solves compaction amnesia)
  • Trust boundary separates curated knowledge (wiki/) from untrusted content (raw/, sessions/), with sanctioned CLI commands for each tier
  • KB.md template teaches Claude to ingest sources, answer queries, and lint your vault

Install

Requires Bun — the CLI and hooks run TypeScript directly.

bunx @beaudry/kb init

Scaffolds ~/kb with the vault structure. init does not touch Claude Code configuration — hooks ship with the KB plugin:

claude plugin marketplace add JustinBeaudry/kb
claude plugin install kb@kb

Safe to run init again — idempotent.

Custom vault path

bunx @beaudry/kb init --vault-path /path/to/vault

Per-project vault

Create a .kb file in your project root containing the vault path:

/path/to/project/vault

Usage

Ingest

Give Claude any source — file path, URL, pasted text, or conversation context:

"Ingest this article on dependency injection"

Claude reads source, copies files to raw/ for provenance, presents takeaways for confirmation, writes wiki pages, cascades updates to related pages, updates index and log. Single ingest typically touches 5-15 pages.

Query

Ask Claude anything your vault might know:

"What decisions did we make about the auth system?"

Claude checks index, follows wikilinks, answers with citations. Novel insights get filed as new wiki pages automatically.

Lint

Ask Claude to check vault health:

"Lint the vault"

Reports orphan pages, dead links, missing frontmatter, stale content, missing types, and contradictions.

Refine

Ask Claude to improve vault structure:

"Refine the vault"

Finds stale pages, under-connected pages, merge/split candidates, and backlink gaps. Presents findings for approval, then applies changes. Shows vault health before and after.

Extract

Extract knowledge from session manifests into wiki pages:

"Extract from sessions"

Sessions are sources. Claude enumerates unprocessed manifests with kb sessions --unprocessed, generates cached summaries with kb summarize, retrieves them through the ask-gated kb read-session, runs the standard ingest workflow on confirmed items, and marks finished manifests with kb mark-extracted. Summaries require the claude CLI (or a KB_SUMMARIZE_COMMAND equivalent) — without one, kb summarize exits nonzero and extraction cannot proceed.

Toggle session-start nudge: /kb:extract on or /kb:extract off.

CLI reference

CommandWhat it does
kb initScaffold the vault (does not register hooks)
kb doctorCheck vault health, hook wiring, and inject-budget pressure
kb uninstallPrint plugin-removal instructions; vault is preserved
kb map [query]Budget-bounded structural map of the wiki — node summaries for navigation
kb get-node <id>Fetch a page or section by node ID (--neighbors, --follow-wikilinks <n>)
kb recall <query>Search curated pages, return evidence envelope
kb get <page>Fetch a curated page by name
kb list-topicsList index topics
kb read-raw <file>Ask-gated bounded read from raw/
kb read-session <file>Ask-gated bounded read from sessions/ (incl. summaries/)
kb sessions [--unprocessed]List session manifest names — never content
kb mark-extracted <file>Mark a manifest as extracted
kb capture-sessionWrite a session manifest (used by the Stop hook)
kb summarize <manifest>Generate or reuse a cached session summary
kb summaries pin|unpinPin or unpin a cached summary

Trust boundary

Vault content is two-tier:

  • Curated (wiki/, index.md, context.md) — trusted, retrieved via kb recall, kb get, kb list-topics.
  • Untrusted (raw/, sessions/) — provenance and machine-generated content, readable only through the ask-gated kb read-raw / kb read-session (bounded excerpts, explicit --approve or KB_APPROVE=1 in non-interactive use).

All retrieval commands emit a length-prefixed JSON envelope with source attribution, and access is recorded in .kb/access-log.jsonl with hashed queries — never plaintext. The plugin ships deny rules that block direct Read/Grep of raw/ and sessions/, plus a security-self-test hook that detects when those rules regress.

Page types

Every wiki page has a type in frontmatter:

TypePurpose
conceptIdeas, techniques, patterns
entityPeople, orgs, tools, projects
source-summaryDigest of a raw/ document
comparisonX vs Y trade-off analysis
overviewGuided index of a topic area

Each type has a structural template defined in KB.md with recommended sections.

Vault structure

~/kb/
  KB.md           # Schema — conventions, workflows, rules
  context.md      # Working set — current focus areas
  index.md        # Categorized pointer index, grouped by topic
  log.md          # Chronological operation log (heading-level entries)
  wiki/           # Knowledge pages (agent-maintained, typed)
  raw/            # Source documents (immutable, provenance)
  sessions/       # Session manifests (auto-generated)
    summaries/    # Cached summaries from manifests
    .trash/       # Non-destructive quarantine for replaced summaries
  .kb/            # Operational state (not knowledge)
    state.json    #   toggles (e.g. autoExtractNudge)
    config.json   #   inject_mode and other settings
    *.jsonl       #   access and inject logs, hashed queries only

Context injection

The inject hook has three modes, resolved in priority order: KB_INJECT_MODE env var → inject_mode in .kb/config.json → eager.

  • lazy — the default written to .kb/config.json on fresh installs. Injects a ~500-byte pointer (vault location, topic headings, retrieval commands); the agent pulls content on demand via kb recall/kb get.
  • eager — the fallback for vaults without a config. Injects content directly under a 32KB budget (configurable via KB_BUDGET), in priority order:
    1. context.md — working set, always first
    2. index.md — categorized page index
    3. Recent sessions — cached summaries first, then manifests as fallback
  • off — no injection.

kb doctor warns when the eager budget is under pressure.

Environment variables

VariableEffect
KB_VAULTVault location (overrides ~/kb and per-project .kb files)
KB_INJECT_MODElazy | eager | off — overrides .kb/config.json
KB_BUDGETEager-mode injection budget in bytes (default 32768)
KB_MAP_BUDGETkb map output budget in bytes (default 16384); --budget overrides
KB_SUMMARIZE_COMMANDSummarizer command (default claude -p --model haiku)
KB_APPROVE1 approves ask-gated reads non-interactively

Search (optional)

For larger vaults, qmd provides BM25 + vector hybrid search over markdown files.

# Install
npm install -g @tobilu/qmd

# Register vault
qmd collection add ~/kb --name kb --mask "**/*.md"
qmd embed

# Add MCP server to Claude Code
# In your Claude Code MCP config:
# { "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }

When qmd MCP tools are available, Query and Refine workflows use qmd_deep_search before falling back to manual index reading.

Model choice

Stop hooks do not call an LLM. Summaries are generated on demand by kb summarize, which calls claude -p --model haiku by default. For tests or custom integrations, set KB_SUMMARIZE_COMMAND to a compatible command.

Uninstall

bunx @beaudry/kb uninstall

Prints the plugin-removal command (claude plugin remove kb). Your vault is preserved either way.

License

MIT

Ver o original no GitHub

Bom para

Relacionados