@andy-toolforge/knowledge-base

Filesystem-first knowledge base facade for AI agents. Zero-dependency CommonJS package: a JSON store with CRUD/search, optional best-effort Supermemory/Serena adapters, MCP tools (kb_*), and a management skill installed into client projects.

Part of the @andy-toolforge monorepo. CommonJS by design — no build step, works in any Node project.

Why

Agents re-learn the same lessons every session. This package gives any project a durable, structured memory:

• Filesystem-first — ~/.toolforge/kb/index.json, no service, no network, no schema.
• Zero dependencies — drop it in anywhere.
• Skill + MCP — agents get both a management skill (installed via postinstall) and kb_* MCP tools.
• Best-effort adapters — mirrors entries to Supermemory/Serena CLIs when present; silently falls back to the filesystem store otherwise.

Install

npm install @andy-toolforge/knowledge-base

The postinstall copies skills/knowledge-base-management.md into the client project's .opencode/skills/ (prefixed knowledge-base-).

Usage

const { KnowledgeBase } = require('@andy-toolforge/knowledge-base');

const kb = new KnowledgeBase(); // default dir ~/.toolforge/kb
// custom: new KnowledgeBase({ dir: './.kb' })

const entry = kb.add({
  type: 'pattern',
  text: 'Use tmp+rename for atomic file writes',
  tags: ['files', 'atomic'],
  source: 'retro-2026-08',
});
// => { id: 'pattern-use-tmp-rename-...', type: 'pattern', text: ..., tags: [...], source: ..., createdAt }

kb.get(entry.id);            // entry or null
kb.search({ query: 'atomic' });            // substring search
kb.search({ query: 'writes', tags: ['files'] });
kb.list({ type: 'pattern' });              // newest first
kb.list({ tags: ['atomic'] });
kb.forget(entry.id);         // { ok, removed }
kb.status();                 // { dir, entries, adapters: { supermemory, serena } }

Entry shape: { id, type, text, tags: string[], source, createdAt }. Types: note | fact | decision | pattern | error-solution | reference. Writes are atomic (tmp + rename).

MCP tools

mcp-tools.js auto-discovered by @andy-toolforge/mcp: kb_add, kb_search, kb_list, kb_get, kb_forget, kb_status.

Adapting to external memory

On add, if the supermemory (or serena) CLI is on PATH, the entry is mirrored to it best-effort. Failures are silent — the filesystem store is always canonical.

Testing

npm test -w @andy-toolforge/knowledge-base

Uses Node's built-in test runner (node --test), co-located in lib/index.test.js (runs against a temp dir — never touches the real ~/.toolforge/kb).

License

MIT