kernl CLAUDE.md

export function createFooModule(): KernelModule {
  let tools: ToolDefinition[] = [];
  return {
    name: "foo",
    async initialize(ctx: ModuleContext) {
      runMigrations(ctx.sqlite, "foo", fooMigrations);  // if has tables
      const service = new FooService(ctx.sqlite, ctx.neo4j);
      tools = fooTools(service);
    },
    getTools() { return tools; },
    async shutdown() {},
  };
}

ModuleContext: { sqlite, neo4j, events, config }

Migrations use Migration { version: number; sql: string } arrays, located in:

• services/kernel/src/modules/{name}/migrations/*.ts (directory pattern), or
• services/kernel/src/modules/{name}/migrations.ts (inline pattern)

SQLite NOT NULL columns with empty defaults: contacts table: email, phone, company, notes are NOT NULL DEFAULT ''. Use <> '' to check for presence, NOT IS NOT NULL. Same pattern used in many other tables (communications, events, etc.)

Google sync source column: source column lives in google_sync_map table, NOT in contacts — join via local_id = contacts.id.

Neo4j is Kernl's own, and it starts empty: The stack brings up a dedicated Neo4j (kernl-public-neo4j) that holds nothing but Kernl's data. It is not shared with any other dataset — an earlier version of this file claimed it shared a database with a SNOMED CT medical ontology and that every query had to filter Kernl nodes; that belonged to a different project's stack and never applied here.