KB Mod

Local knowledge-vault Capability. Provides:

• cap.kb.read — read a markdown file from the configured local moltbank-kb checkout. Returns content + parsed frontmatter.
• cap.kb.search — recursive substring search across markdown files in the vault, bounded by depth 6 and 1 MB per file.
• cap.kb.propose — append an entry to temp/<owner>.md following the moltbank-kb proposal schema for human / reconciler review.

The mod is filesystem-backed (does not call the Anthropic-hosted Moltbank-KB MCP). The agent-facing capability surface is the same; consumers do not need to know how kb-mod resolves a path.

Install

moltbank mod install kb

Lifecycle

moltbank mod setup kb            # writes config: kbRoot path
moltbank mod doctor kb --json    # validates kbRoot, INDEX.md presence, writeAllowed
moltbank mod estimate kb --json
moltbank mod status kb --json

Used as a capability provider

import { useKB } from '@moltbankhq/mod-sdk';

const kb = useKB();
const file = await kb.read({ path: 'wiki/team/people/cap.md' });
const hits = await kb.search({ query: 'x402 onboarding', limit: 10 });
await kb.propose({
  owner: 'cap',
  target: 'wiki/team/people/cap.md',
  type: 'add-section',
  reason: 'recording onboarding milestone',
  content: '... markdown ...'
});

Path safety

Every path and target is resolved under kbRoot and rejected if the resolved location escapes the root. Absolute paths and .. traversal are blocked at the helper layer before any filesystem call.

Caveats

• Search is plain substring with light frontmatter / H1 boost — no fuzzy or semantic ranking. Sufficient for KB-scale corpora; revisit later if vaults grow.
• cap.kb.propose only appends entries to temp/<owner>.md. The reconciler (moltbank-kb/code/reconcile-temp.mjs) is what actually applies validated proposals to wiki/. That reconciliation step is out of kb-mod scope.
• Set config.writeAllowed: false to run kb-mod read-only on a host where proposals are not desired (returns KB_WRITE_FORBIDDEN).