memdb

1import type { Engine, Register } from 'claude-code'
2
3import { HELP, NOTE, PLUGIN, PREFLIGHT, TOOLS, commandArgs, preflightMessage } from './memdb'
4import type { Args } from './memdb'
5
6type Outcome = { ok: true; text: string } | { ok: false; text: string }
7
8type Config = { python: string; dbPath: string }
9
10// The python check passes once per python command and is then remembered; a failure is retried on the next call.
11const checked = new Set<string>()
12
13async function check($: Engine, python: string): Promise<string | undefined> {
14  if (checked.has(python)) return undefined
15  try {
16    const r = await $.process.run([python, '-c', PREFLIGHT], { timeoutMs: 15_000 })
17    if (r.exitCode !== 0) return preflightMessage(python, r.exitCode, r.stdout)
18  } catch {
19    return `memdb could not start "${python}": it is not installed or not on PATH. Install Python 3.8+ or set the "python" option of the memdb plugin.`
20  }
21  checked.add(python)
22  return undefined
23}
24
25async function run($: Engine, cfg: Config, args: string[], stdin?: string): Promise<Outcome> {
26  const problem = await check($, cfg.python)
27  if (problem) return { ok: false, text: problem }
28  try {
29    const r = await $.process.run([cfg.python, `${$.plugin.root}/bin/memdb.py`, ...args], {
30      ...(stdin !== undefined ? { stdin } : {}),
31      ...(cfg.dbPath ? { env: { MEMDB_PATH: cfg.dbPath } } : {}),
32      timeoutMs: 60_000,
33    })
34    const out = r.stdout.trim()
35    const err = r.stderr.trim()
36    if (r.exitCode !== 0) return { ok: false, text: `memdb failed (exit ${r.exitCode}): ${err || out || 'no output'}` }
37    return { ok: true, text: out || err || 'Done.' }
38  } catch (e) {
39    return { ok: false, text: `memdb could not run: ${String(e)}` }
40  }
41}
42
43// Runs one tool call: builds its argv, runs memdb.py, and answers with the output (or an error the model reads).
44async function serve($: Engine, cfg: Config, name: string, e: unknown): Promise<{ result: string } | { deny: string }> {
45  const t = TOOLS.find(x => x.name === name)!
46  let built
47  try {
48    built = t.build(e as Args)
49  } catch (err) {
50    return { deny: `${name}: ${(err as Error).message}` }
51  }
52  const out = await run($, cfg, built.args, built.stdin)
53  return out.ok ? { result: out.text } : { deny: out.text }
54}
55
56const failed = () => ({ deny: 'memdb: the tool failed unexpectedly.' })
57
58export const register: Register = (on, options) => {
59  const cfg: Config = {
60    python: (typeof options.python === 'string' && options.python.trim()) || 'python3',
61    dbPath: typeof options.dbPath === 'string' ? options.dbPath.trim() : '',
62  }
63  const promptNote = options.promptNote !== false
64
65  on('session.start', async ($, e, next) => {
66    for (const t of TOOLS) {
67      await $.tool.register({ name: t.name, description: t.description, inputSchema: t.inputSchema, isDeferred: false })
68    }
69    await $.command.register({
70      name: 'memdb',
71      description: 'Search the memory database (/memdb <words>), or: stats, list, get <name>, sync',
72      argumentHint: '<words> | stats | list | get <name> | sync',
73    })
74    return next(e)
75  })
76
77  // One hook per tool, each with its literal name.
78  on('tool.call', { tool: 'mcp__memdb__memdb_search' }, ($, e) => serve($, cfg, 'memdb_search', e)).catch(failed)
79  on('tool.call', { tool: 'mcp__memdb__memdb_add' }, ($, e) => serve($, cfg, 'memdb_add', e)).catch(failed)
80  on('tool.call', { tool: 'mcp__memdb__memdb_get' }, ($, e) => serve($, cfg, 'memdb_get', e)).catch(failed)
81  on('tool.call', { tool: 'mcp__memdb__memdb_index' }, ($, e) => serve($, cfg, 'memdb_index', e)).catch(failed)
82  on('tool.call', { tool: 'mcp__memdb__memdb_forget' }, ($, e) => serve($, cfg, 'memdb_forget', e)).catch(failed)
83
84  on('command.run', { command: 'memdb' }, async ($, e) => {
85    const args = commandArgs(e.args)
86    if (args === 'help') return { text: HELP }
87    return { text: (await run($, cfg, args)).text }
88  })
89
90  if (promptNote) {
91    on('prompt.compose', async ($, e, next) => {
92      const r = await next(e)
93      return { sections: [...r.sections, { id: `${PLUGIN}:note`, text: NOTE, scope: 'session' as const }] }
94    }).catch(($, e, next) => next(e))
95  }
96}
97

1// Pure helpers for the memdb mod: tool definitions, argv building, python preflight.
2
3export type Args = Record<string, unknown>
4export type Run = { argv: string[]; stdin?: string }
5
6export const PLUGIN = 'memdb'
7
8const str = (v: unknown) => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v))
9const opt = (flag: string, v: unknown): string[] => (str(v).trim() === '' ? [] : [flag, str(v)])
10
11/** A required string argument, or a message saying which is missing. */
12function need(a: Args, key: string): string {
13  const v = str(a[key]).trim()
14  if (!v) throw new Error(`Missing required argument "${key}".`)
15  return v
16}
17
18export type ToolDef = {
19  name: string
20  description: string
21  inputSchema: Record<string, unknown>
22  /** The memdb.py arguments (after the script path), plus stdin when the body goes there. */
23  build: (a: Args) => { args: string[]; stdin?: string }
24}
25
26const KINDS = ['memory', 'note', 'doc', 'transcript']
27const TYPES = ['user', 'feedback', 'project', 'reference']
28
29export const TOOLS: ToolDef[] = [
30  {
31    name: 'memdb_search',
32    description:
33      'Ranked full-text search over the memory database: Claude memory files, saved notes, indexed docs and saved past conversations (at most two of those by default; kind transcript for all). Use it before rereading a long notes file or when you need a fact you may have stored. Returns matching entries with snippets (set full to get whole bodies).',
34    inputSchema: {
35      type: 'object',
36      properties: {
37        query: { type: 'string', description: 'Words to search for; every word must match (prefix ok), with an any-word fallback.' },
38        kind: { type: 'string', enum: KINDS, description: 'Only this kind of entry.' },
39        project: { type: 'string', description: 'Only entries whose project contains this text.' },
40        limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Max results (default 8).' },
41        full: { type: 'boolean', description: 'Return full bodies instead of snippets.' },
42      },
43      required: ['query'],
44    },
45    build: a => ({
46      args: [
47        'search',
48        ...opt('-k', a.kind),
49        ...opt('-p', a.project),
50        ...opt('-n', a.limit),
51        ...(a.full === true ? ['-f'] : []),
52        '--',
53        need(a, 'query'),
54      ],
55    }),
56  },
57  {
58    name: 'memdb_add',
59    description:
60      'Save or replace a note in the memory database (names are unique: adding an existing name replaces it). Use it for niche facts that are too small or too many for the always-loaded memory file.',
61    inputSchema: {
62      type: 'object',
63      properties: {
64        name: { type: 'string', description: 'Short slug, e.g. "staging-db-port".' },
65        body: { type: 'string', description: 'The note text.' },
66        type: { type: 'string', enum: TYPES, description: 'user | feedback | project | reference (default project).' },
67        project: { type: 'string', description: 'Project the note belongs to.' },
68        desc: { type: 'string', description: 'One-line description, searched with higher weight than the body.' },
69      },
70      required: ['name', 'body'],
71    },
72    build: a => ({
73      args: ['add', '-t', str(a.type).trim() || 'project', ...opt('-d', a.desc), ...opt('-p', a.project), '--', need(a, 'name'), '-'],
74      stdin: need(a, 'body'),
75    }),
76  },
77  {
78    name: 'memdb_get',
79    description: 'Show full entries by name (exact or substring match), up to 5.',
80    inputSchema: {
81      type: 'object',
82      properties: { name: { type: 'string', description: 'Entry name or part of it.' } },
83      required: ['name'],
84    },
85    build: a => ({ args: ['get', '--', need(a, 'name')] }),
86  },
87  {
88    name: 'memdb_index',
89    description:
90      'Index markdown files (handoff notes, plans, long docs) into the database, split by heading, so memdb_search can find parts of them. Indexed files are re-synced automatically when they change.',
91    inputSchema: {
92      type: 'object',
93      properties: {
94        paths: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Markdown file paths.' },
95        project: { type: 'string', description: 'Project label for these docs.' },
96      },
97      required: ['paths'],
98    },
99    build: a => {
100      const paths = Array.isArray(a.paths) ? a.paths.map(str).filter(s => s.trim() !== '') : []
101      if (paths.length === 0) throw new Error('Missing required argument "paths".')
102      return { args: ['index', ...opt('-p', a.project), '--', ...paths] }
103    },
104  },
105  {
106    name: 'memdb_forget',
107    description: 'Delete a note that was saved with memdb_add. Memory files are removed by deleting the .md file instead.',
108    inputSchema: {
109      type: 'object',
110      properties: { name: { type: 'string', description: 'Exact note name.' } },
111      required: ['name'],
112    },
113    build: a => ({ args: ['forget', '--', need(a, 'name')] }),
114  },
115]
116
117/** Checked once per session before the first call: Python 3.8+, with SQLite FTS5. */
118export const PREFLIGHT = [
119  'import sys',
120  'if sys.version_info < (3, 8):',
121  '    sys.stdout.write(sys.version.split()[0]); sys.exit(3)',
122  'import sqlite3',
123  'try:',
124  '    sqlite3.connect(":memory:").execute("create virtual table t using fts5(a)")',
125  'except Exception:',
126  '    sys.stdout.write(sqlite3.sqlite_version); sys.exit(4)',
127].join('\n')
128
129export function preflightMessage(python: string, exitCode: number, stdout: string): string {
130  if (exitCode === 3) return `memdb needs Python 3.8 or newer, but ${python} is ${stdout.trim() || 'older'}. Install a newer Python or set the "python" option of the memdb plugin.`
131  if (exitCode === 4) return `memdb needs SQLite with FTS5, which this Python's sqlite3 (${stdout.trim() || 'unknown version'}) lacks. Use a Python built with FTS5 (python.org or Homebrew builds have it) via the "python" option.`
132  return `memdb could not run ${python} (exit ${exitCode}). Install Python 3.8+ or set the "python" option of the memdb plugin.`
133}
134
135export const NOTE = `[memdb] A searchable memory database is available through the tools memdb_search, memdb_add, memdb_get and memdb_index (mcp__memdb__*). Search it before rereading long notes or memory files, and store niche facts that do not belong in the always-loaded memory with memdb_add.`
136
137export const HELP = `/memdb <words>        search memories, notes and indexed docs
138/memdb stats          counts and database size
139/memdb list           list memories and notes
140/memdb get <name>     show an entry in full
141/memdb sync           re-sync memory files now
142Tools for Claude: memdb_search, memdb_add, memdb_get, memdb_index, memdb_forget`
143
144/** What a /memdb command line means, as memdb.py arguments. */
145export function commandArgs(raw: string): string[] | 'help' {
146  const text = raw.trim()
147  if (text === '' || text === 'help') return 'help'
148  const [verb = '', ...rest] = text.split(/\s+/)
149  const tail = rest.join(' ')
150  if (rest.length === 0 && (verb === 'stats' || verb === 'list' || verb === 'sync')) return [verb]
151  if (verb === 'get' && tail) return ['get', '--', tail]
152  return ['search', '--', text]
153}
154