mindkeg-mcp: Instructions file for Claude Code

Mind Keg MCP — Development Guide for AI Agents

This file provides persistent context for AI agents (Claude Code, Cursor, Windsurf, etc.) working on this codebase. This project dogfoods its own concept: it IS a persistent memory system for agents, and we use it on itself.

Project Overview

Mind Keg MCP is a TypeScript/Node.js MCP server that stores, searches, and retrieves atomic developer learnings. It is designed to give AI agents persistent memory across sessions.

• Version: 0.7.1
• Runtime: Node.js >= 22 (uses built-in node:sqlite)
• Transport: stdio (local) + HTTP+SSE (remote)
• Storage: SQLite via node:sqlite (DatabaseSync — synchronous)
• Search: Semantic (FastEmbed local ONNX or OpenAI embeddings) with FTS5 fallback when no embedding provider is configured
• Auth: stdio transport is auth-free (local use); HTTP transport requires API key (SHA-256 hashed, never stored in plaintext)
• License: MIT

Repository Layout

cli/
  index.ts              CLI entry point (Commander.js)
  commands/
    api-key.ts          API key management (generate, list, revoke)
    backfill-integrity.ts Compute and store integrity hashes for existing learnings
    decrypt-db.ts       Decrypt database content/embedding fields in-place
    dedup-scan.ts       Backfill duplicate_candidates for existing learnings
    encrypt-db.ts       Encrypt database content/embedding fields in-place
    export.ts           Export learnings to JSON
    import.ts           Import learnings from JSON
    init.ts             Project setup (copies AGENTS.md template)
    migrate.ts          Run database migrations
    purge.ts            Purge expired or filtered learnings
    serve.ts            Start stdio or HTTP server
    stats.ts            Database statistics

src/
  index.ts              Server entry point, transport setup
  server.ts             MCP server, tool registration
  config.ts             Config loading (env vars → Zod-validated defaults)
  audit/
    audit-logger.ts     Structured JSON lines audit log writer (AuditLogger class)
    index.ts            Audit barrel export
  auth/
    api-key.ts          API key generation (crypto.randomBytes + SHA-256)
    middleware.ts        API key validation middleware
  crypto/
    encryption.ts       AES-256-GCM field encryption (encrypt, decrypt, isEncrypted, parseEncryptionKey)
    index.ts            Crypto barrel export
  monitoring/
    health.ts           GET /health handler (status, version, uptime, DB connectivity)
    metrics.ts          Prometheus metrics registry and metric definitions (prom-client)
    index.ts            Monitoring barrel export
  security/
    integrity.ts        SHA-256 integrity hash computation and verification
    rate-limiter.ts     In-memory token bucket rate limiter (per-key, read/write buckets)
    sanitize.ts         Content sanitization (strip control chars, reject whitespace-only)
    index.ts            Security barrel export
  hooks/
    generate-hook.ts    Hook script generation for SessionStart auto-retrieval
  tools/                MCP tool handlers
    consolidated/       8 consolidated tools (primary API)
      get-context.ts    Unified retrieval (session primer, entity context, search)
      store.ts          Unified storage (learning, decision, finding, gotcha)
      update.ts         Unified lifecycle (update, deprecate, flag_stale, delete, merge)
      resolve.ts        Close out decisions or findings
      query.ts          List knowledge by type
      list-scopes.ts    List repositories and workspaces
    [19 alias files]    Backwards-compatible aliases delegating to consolidated tools
    tool-utils.ts       Shared tool utilities (getActorFromApiKey, recordToolMetrics)
  services/
    learning-service.ts Business logic for CRUD + search + getContext
    embedding-service.ts Embedding provider abstraction
    purge-service.ts    Orchestrates TTL-based and filter-based purge operations
    conflict-detector.ts Keyword-heuristic conflict detection
    staleness-engine.ts Staleness score computation and periodic recomputation
    ranking.ts          Pure ranking function for get_context
    budget.ts           Pure budget allocation/trimming for get_context
    index.ts            Service barrel export
  storage/
    storage-adapter.ts  StorageAdapter interface
    sqlite-adapter.ts   SQLite implementation
    storage-factory.ts  Factory for creating adapters
    migrations/
      001-initial.ts    Initial schema + FTS5 triggers
      002-duplicate-candidates.ts  Near-duplicate detection table
      003-ttl-and-provenance.ts    ttl_days, source_agent, integrity_hash columns
      004-smarter-knowledge-management.ts  SKM schema migration (access tracking, conflicts, relationships, staleness)
  models/
    learning.ts         Zod schemas + TypeScript types (core entity)
    repository.ts       Repository model
    workspace.ts        Workspace model (WS-AC-4)
    index.ts            Model barrel export
  utils/
    errors.ts           Typed error classes (MindKegError hierarchy)
    logger.ts           Pino logger → stderr
    index.ts            Utils barrel export

templates/
  AGENTS.md             Template users copy to their repos via `mindkeg init`

tests/
  unit/
    audit-logger.test.ts
    auth.test.ts
    budget.test.ts
    embedding-service.test.ts
    encryption.test.ts
    get-context.test.ts
    init.test.ts
    integrity.test.ts
    learning-service.test.ts
    migration-003.test.ts
    models.test.ts
    monitoring.test.ts
    purge-service.test.ts
    ranking.test.ts
    rate-limiter.test.ts
    sanitize.test.ts
    stats.test.ts
    workspace.test.ts
  integration/
    audit.test.ts
    backfill-integrity.test.ts
    e2e-sqlite.test.ts
    encryption.test.ts
    get-context.test.ts
    migration-003.test.ts
    provenance.test.ts
    purge.test.ts
    sqlite-adapter.test.ts

.github/workflows/
  ci.yml                CI: typecheck → lint → test → build (Node 22, ubuntu + windows)
  publish.yml           Publish to npm on GitHub release (with provenance)