@onmars/lunar-memory-brain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onMars Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @onmars/lunar-memory-brain
+
+Brain memory provider (Supabase-backed) for [Lunar](https://github.com/onmars-tech/lunar).
+
+This package is used internally by `@onmars/lunar-cli`. Install the CLI instead:
+
+```bash
+bun install -g @onmars/lunar-cli
+```
+
+## License
+
+MIT — [onMars Tech](https://github.com/onmars-tech)

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onmars/lunar-memory-brain",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src/", "LICENSE"],
+  "dependencies": {
+    "@onmars/lunar-core": "0.1.0"
+  },
+  "description": "Brain memory provider for Lunar (Supabase-backed long-term memory)",
+  "author": "onMars Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onmars-tech/lunar",
+    "directory": "packages/memory-brain"
+  },
+  "homepage": "https://github.com/onmars-tech/lunar",
+  "bugs": "https://github.com/onmars-tech/lunar/issues",
+  "keywords": ["lunar", "ai", "memory", "supabase", "bun"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"bun": ">=1.2"
+}
+}

package/src/__tests__/client.test.ts

@@ -0,0 +1,472 @@
+/**
+ * # BrainClient — Functional Specification
+ *
+ * Implements the `MemoryProvider` interface for lunar-brain (Postgres-backed
+ * semantic memory API).
+ *
+ * ## MemoryProvider contract (generic):
+ * - `init()` → health check (throws if brain is unreachable)
+ * - `destroy()` → no-op (HTTP client, no persistent connection)
+ * - `recall(query, options?)` → search memories by semantic similarity
+ * - `save(facts)` → batch-save generic facts
+ * - `health()` → `{ ok, error? }`
+ * - `agentInstructions()` → returns brain API reference for the agent's system prompt
+ *
+ * ## Brain-specific extensions:
+ * - `saveFact(fact)` → save with brain-specific fields (domain, category, importance, tags, decay)
+ * - `createEntity(entity)` → knowledge graph nodes (person, project, concept, etc.)
+ * - `createRelation(relation)` → knowledge graph edges (works_at, knows, etc.)
+ * - `listEntities(options?)` → paginated entity listing
+ * - `extractPipeline(text, channel, date)` → LLM-powered extraction (facts + entities + relations + episode)
+ *
+ * ## Brain API response format:
+ * Paginated endpoints return `{ data: T[], count: number }`.
+ * Recall results: `{ source, id, score, data: { ...details } }` — note `source` not `type`,
+ * and entity details are nested in `data`.
+ *
+ * ## Auth:
+ * Optional API key → `Authorization: Bearer <key>` header. No key → no header.
+ * Currently brain is Docker-internal (no auth needed), but the client supports it.
+ */
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
+import { BrainClient } from '../client'
+
+const originalFetch = globalThis.fetch
+
+describe('BrainClient', () => {
+  let client: BrainClient
+
+  beforeEach(() => {
+    client = new BrainClient({ url: 'http://localhost:8082', timeoutMs: 5000 })
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  // ─── Constructor ─────────────────────────────────────────────────
+
+  describe('constructor — URL and timeout configuration', () => {
+    it('normalizes trailing slashes from URL', () => {
+      const c = new BrainClient({ url: 'http://brain:8082///' })
+      expect((c as any).url).toBe('http://brain:8082')
+    })
+
+    it('stores API key for auth header injection', () => {
+      const c = new BrainClient({ url: 'http://brain:8082', apiKey: 'test-key' })
+      expect((c as any).apiKey).toBe('test-key')
+    })
+
+    it('defaults timeout to 10 seconds', () => {
+      const c = new BrainClient({ url: 'http://brain:8082' })
+      expect((c as any).timeoutMs).toBe(10000)
+    })
+
+    it('accepts custom timeout', () => {
+      const c = new BrainClient({ url: 'http://brain:8082', timeoutMs: 30000 })
+      expect((c as any).timeoutMs).toBe(30000)
+    })
+  })
+
+  // ─── Health check ────────────────────────────────────────────────
+
+  describe('health — brain availability check', () => {
+    it('returns ok:true when brain responds with status "ok"', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response(JSON.stringify({ status: 'ok' }), { status: 200 })),
+      ) as any
+
+      const result = await client.health()
+      expect(result.ok).toBe(true)
+      expect(result.error).toBeUndefined()
+    })
+
+    it('returns ok:false with HTTP status on server error', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response('Internal Server Error', { status: 500 })),
+      ) as any
+
+      const result = await client.health()
+      expect(result.ok).toBe(false)
+      expect(result.error).toBe('HTTP 500')
+    })
+
+    it('returns ok:false with error message on network failure', async () => {
+      globalThis.fetch = mock(() => Promise.reject(new Error('ECONNREFUSED'))) as any
+
+      const result = await client.health()
+      expect(result.ok).toBe(false)
+      expect(result.error).toContain('ECONNREFUSED')
+    })
+
+    it('returns ok:false when status is not "ok" (degraded)', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response(JSON.stringify({ status: 'degraded' }), { status: 200 })),
+      ) as any
+
+      const result = await client.health()
+      expect(result.ok).toBe(false)
+    })
+  })
+
+  // ─── Init ────────────────────────────────────────────────────────
+
+  describe('init — startup health gate', () => {
+    it('passes silently when brain is healthy', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response(JSON.stringify({ status: 'ok' }), { status: 200 })),
+      ) as any
+
+      await client.init() // should not throw
+    })
+
+    it('throws if brain is unreachable (fail-fast at startup)', async () => {
+      globalThis.fetch = mock(() => Promise.resolve(new Response('error', { status: 500 }))) as any
+
+      expect(client.init()).rejects.toThrow('Brain health check failed')
+    })
+  })
+
+  // ─── Recall ──────────────────────────────────────────────────────
+
+  describe('recall — semantic memory search', () => {
+    it('sends POST /recall and unwraps paginated { data, count } response', async () => {
+      const mockResponse = {
+        data: [
+          {
+            source: 'fact',
+            id: '1',
+            score: 0.9,
+            data: { id: '1', content: 'test fact', domain: 'work', category: 'decision' },
+          },
+        ],
+        count: 1,
+      }
+
+      let capturedUrl = ''
+      let capturedBody = ''
+
+      globalThis.fetch = mock(async (url: string, init: any) => {
+        capturedUrl = url
+        capturedBody = init.body
+        return new Response(JSON.stringify(mockResponse), { status: 200 })
+      }) as any
+
+      const results = await client.recall('test query', { limit: 5, minScore: 0.5 })
+
+      expect(capturedUrl).toBe('http://localhost:8082/recall')
+      expect(JSON.parse(capturedBody)).toEqual({ query: 'test query', limit: 5, minScore: 0.5 })
+      expect(results).toHaveLength(1)
+      expect(results[0].content).toBe('test fact')
+      expect(results[0].score).toBe(0.9)
+      expect(results[0].metadata?.type).toBe('fact')
+    })
+
+    it('maps all 5 source types to MemoryResult format', async () => {
+      // Brain uses `source` field (not `type`) and nests details in `data`
+      const mockResponse = {
+        data: [
+          { source: 'fact', id: '1', score: 0.9, data: { id: '1', content: 'a fact' } },
+          { source: 'entity', id: '2', score: 0.8, data: { id: '2', name: 'Alice' } },
+          {
+            source: 'episode',
+            id: '3',
+            score: 0.7,
+            data: { id: '3', summary: 'session', keyOutcomes: ['shipped v0.2'] },
+          },
+          {
+            source: 'relation',
+            id: '4',
+            score: 0.6,
+            data: { id: '4', description: 'works at', relationType: 'works_at' },
+          },
+          { source: 'summary', id: '5', score: 0.5, data: { id: '5', summary: 'weekly summary' } },
+        ],
+        count: 5,
+      }
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response(JSON.stringify(mockResponse), { status: 200 })),
+      ) as any
+
+      const results = await client.recall('test')
+
+      expect(results[0].content).toBe('a fact') // fact → content
+      expect(results[1].content).toBe('[Entity: Alice]') // entity → name
+      expect(results[2].content).toContain('session') // episode → summary
+      expect(results[2].content).toContain('shipped v0.2') // episode → keyOutcomes
+      expect(results[3].content).toBe('works at') // relation → description
+      expect(results[4].content).toBe('weekly summary') // summary → summary
+    })
+
+    it('returns empty array for no results', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response(JSON.stringify({ data: [], count: 0 }), { status: 200 })),
+      ) as any
+
+      expect(await client.recall('nonexistent')).toHaveLength(0)
+    })
+
+    it('throws with HTTP status on API error', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(new Response('Bad Request', { status: 400 })),
+      ) as any
+
+      expect(client.recall('test')).rejects.toThrow('Brain recall failed (400)')
+    })
+
+    it('passes optional filters (category, tags) to API', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(JSON.stringify({ data: [], count: 0 }), { status: 200 })
+      }) as any
+
+      await client.recall('query', { limit: 3, category: 'decision', tags: ['work'] })
+
+      expect(capturedBody.category).toBe('decision')
+      expect(capturedBody.tags).toEqual(['work'])
+    })
+  })
+
+  // ─── Save ────────────────────────────────────────────────────────
+
+  describe('save — generic MemoryProvider batch save', () => {
+    it('saves each fact as individual POST request', async () => {
+      let callCount = 0
+
+      globalThis.fetch = mock(async () => {
+        callCount++
+        return new Response(JSON.stringify({ id: `id-${callCount}` }), { status: 201 })
+      }) as any
+
+      await client.save([
+        { content: 'fact 1', category: 'observation' },
+        { content: 'fact 2', category: 'decision', importance: 7 },
+      ])
+
+      expect(callCount).toBe(2)
+    })
+  })
+
+  // ─── saveFact (brain-specific) ───────────────────────────────────
+
+  describe('saveFact — brain-specific fields', () => {
+    it('sends all brain-specific fields (domain, tags, decay, confidence)', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(JSON.stringify({ id: 'new-id' }), { status: 201 })
+      }) as any
+
+      const id = await client.saveFact({
+        content: 'Important decision',
+        entityId: 'entity-1',
+        domain: 'work',
+        category: 'decision',
+        importance: 8,
+        tags: ['session:2026-02-28'],
+        sessionDate: '2026-02-28',
+        decayImmune: false,
+        confidence: 0.95,
+      })
+
+      expect(id).toBe('new-id')
+      expect(capturedBody.content).toBe('Important decision')
+      expect(capturedBody.entityId).toBe('entity-1')
+      expect(capturedBody.domain).toBe('work')
+      expect(capturedBody.importance).toBe(8)
+      expect(capturedBody.sessionDate).toBe('2026-02-28')
+      expect(capturedBody.decayImmune).toBe(false)
+      expect(capturedBody.confidence).toBe(0.95)
+    })
+
+    it('omits undefined optional fields from request body', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(JSON.stringify({ id: 'id' }), { status: 201 })
+      }) as any
+
+      await client.saveFact({ content: 'minimal fact' })
+
+      expect(capturedBody.content).toBe('minimal fact')
+      expect(capturedBody.entityId).toBeUndefined()
+      expect(capturedBody.domain).toBeUndefined()
+    })
+  })
+
+  // ─── Auth ────────────────────────────────────────────────────────
+
+  describe('auth — optional Bearer token', () => {
+    it('includes Authorization header when apiKey is configured', async () => {
+      const authClient = new BrainClient({ url: 'http://brain:8082', apiKey: 'secret' })
+      let capturedHeaders: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedHeaders = init.headers
+        return new Response(JSON.stringify({ status: 'ok' }), { status: 200 })
+      }) as any
+
+      await authClient.health()
+      expect(capturedHeaders['Authorization']).toBe('Bearer secret')
+    })
+
+    it('omits Authorization header when no apiKey', async () => {
+      let capturedHeaders: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedHeaders = init.headers
+        return new Response(JSON.stringify({ status: 'ok' }), { status: 200 })
+      }) as any
+
+      await client.health()
+      expect(capturedHeaders['Authorization']).toBeUndefined()
+    })
+  })
+
+  // ─── Agent instructions ──────────────────────────────────────────
+
+  describe('agentInstructions — brain API reference for system prompt', () => {
+    it('documents all brain endpoints (recall, save, entities, etc.)', () => {
+      const instructions = client.agentInstructions()
+
+      expect(instructions).toContain('Brain API')
+      expect(instructions).toContain('Recall')
+      expect(instructions).toContain('Save fact')
+      expect(instructions).toContain('Entities')
+      expect(instructions).toContain('BRAIN_URL')
+    })
+
+    it('includes curl examples for direct API access', () => {
+      const instructions = client.agentInstructions()
+      expect(instructions).toContain('```')
+      expect(instructions).toContain('curl')
+    })
+
+    it('returns substantial content (not a stub)', () => {
+      const instructions = client.agentInstructions()
+      expect(typeof instructions).toBe('string')
+      expect(instructions.length).toBeGreaterThan(100)
+    })
+  })
+
+  // ─── Knowledge graph: entities ───────────────────────────────────
+
+  describe('createEntity — knowledge graph nodes', () => {
+    it('sends entity with type, name, aliases, domains', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(JSON.stringify({ id: 'entity-id' }), { status: 201 })
+      }) as any
+
+      const id = await client.createEntity({
+        type: 'person',
+        name: 'Test Person',
+        aliases: ['TP'],
+        domains: ['work'],
+      })
+
+      expect(id).toBe('entity-id')
+      expect(capturedBody.type).toBe('person')
+      expect(capturedBody.name).toBe('Test Person')
+    })
+  })
+
+  describe('listEntities — paginated entity retrieval', () => {
+    it('unwraps { data, count } response', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              data: [{ id: '1', name: 'Alice', type: 'person' }],
+              count: 1,
+            }),
+            { status: 200 },
+          ),
+        ),
+      ) as any
+
+      const entities = await client.listEntities({ limit: 5 })
+      expect(entities).toHaveLength(1)
+      expect((entities[0] as any).name).toBe('Alice')
+    })
+  })
+
+  // ─── Knowledge graph: relations ──────────────────────────────────
+
+  describe('createRelation — knowledge graph edges', () => {
+    it('sends relation with source, target, type, strength', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(JSON.stringify({ id: 'rel-id' }), { status: 201 })
+      }) as any
+
+      const id = await client.createRelation({
+        sourceId: 'entity-1',
+        targetId: 'entity-2',
+        relationType: 'works_at',
+        strength: 'strong',
+      })
+
+      expect(id).toBe('rel-id')
+      expect(capturedBody.relationType).toBe('works_at')
+    })
+  })
+
+  // ─── Pipeline extraction ─────────────────────────────────────────
+
+  describe('extractPipeline — LLM-powered conversation extraction', () => {
+    it('sends conversation text and returns extraction counts', async () => {
+      let capturedBody: any
+
+      globalThis.fetch = mock(async (_: string, init: any) => {
+        capturedBody = JSON.parse(init.body)
+        return new Response(
+          JSON.stringify({
+            facts: 3,
+            entities: 1,
+            relations: 2,
+            episodeId: 'ep-1',
+          }),
+          { status: 200 },
+        )
+      }) as any
+
+      const result = await client.extractPipeline('conversation text', 'research', '2026-02-28')
+
+      expect(result.facts).toBe(3)
+      expect(result.episodeId).toBe('ep-1')
+      expect(capturedBody.conversation).toBe('conversation text')
+      expect(capturedBody.channel).toBe('research')
+    })
+  })
+
+  // ─── MemoryProvider contract ─────────────────────────────────────
+
+  describe('MemoryProvider interface compliance', () => {
+    it('exposes required id="brain" and name="Lunar Brain"', () => {
+      expect(client.id).toBe('brain')
+      expect(client.name).toBe('Lunar Brain')
+    })
+
+    it('implements all 5 required methods', () => {
+      expect(typeof client.init).toBe('function')
+      expect(typeof client.destroy).toBe('function')
+      expect(typeof client.recall).toBe('function')
+      expect(typeof client.save).toBe('function')
+      expect(typeof client.health).toBe('function')
+    })
+
+    it('destroy() is a clean no-op (HTTP client, no teardown needed)', async () => {
+      await client.destroy() // should not throw
+    })
+  })
+})

package/src/client.ts

@@ -0,0 +1,631 @@
+import type { Fact, MemoryProvider, MemoryResult, SearchOptions } from '@onmars/lunar-core'
+import { log } from '@onmars/lunar-core'
+
+/**
+ * Brain-specific fact with extra fields beyond the generic Fact interface.
+ * Use this when you need brain-specific features (entityId, domain, decayImmune, etc.)
+ */
+export interface BrainFact extends Fact {
+  /** Entity this fact belongs to */
+  entityId?: string
+  /** Knowledge domain */
+  domain?: string
+  /** Confidence score (0.0-1.0) */
+  confidence?: number
+  /** Session date (YYYY-MM-DD) */
+  sessionDate?: string
+  /** Whether this fact is immune to decay */
+  decayImmune?: boolean
+  /** Episode ID this fact belongs to */
+  episodeId?: string
+}
+
+/**
+ * Brain entity for the knowledge graph.
+ */
+export interface BrainEntity {
+  type: string
+  name: string
+  aliases?: string[]
+  domains?: string[]
+  subtype?: string
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Brain relation between two entities.
+ */
+export interface BrainRelation {
+  sourceId: string
+  targetId: string
+  relationType: string
+  strength?: 'weak' | 'moderate' | 'strong'
+  description?: string
+  importance?: number
+}
+
+/**
+ * Brain episode — groups all facts from a session.
+ */
+export interface BrainEpisode {
+  id: string
+  sessionDate: string
+  agentId: string
+  channel?: string
+  summary: string
+  keyOutcomes: string[]
+  topics: string[]
+  moodEnergy?: Record<string, unknown>
+  factIds: string[]
+  entityIds: string[]
+  messageCount?: number
+  durationMinutes?: number
+  importance: number
+  createdAt: string
+}
+
+/**
+ * Raw recall result from the brain API.
+ * API returns { data: BrainRecallResult[], count: number }
+ * Each result has: source (type), id, score, data (nested object with details)
+ */
+interface BrainRecallResult {
+  source: 'fact' | 'entity' | 'relation' | 'episode' | 'summary'
+  id: string
+  score: number
+  data: {
+    id: string
+    content?: string
+    name?: string
+    summary?: string
+    domain?: string
+    category?: string
+    importance?: number
+    entityId?: string
+    tags?: string[]
+    createdAt?: string
+    sessionDate?: string
+    description?: string
+    relationType?: string
+    keyOutcomes?: string[]
+    [key: string]: unknown
+  }
+}
+
+/**
+ * Wrapper for paginated API responses.
+ */
+interface BrainPaginatedResponse<T> {
+  data: T[]
+  count: number
+}
+
+export interface BrainClientOptions {
+  /** Brain API base URL */
+  url: string
+  /** API key for authenticated brains (optional) */
+  apiKey?: string
+  /** Request timeout in milliseconds (default: 10000) */
+  timeoutMs?: number
+}
+
+/**
+ * BrainClient — MemoryProvider implementation for lunar-brain.
+ *
+ * Wraps the lunar-brain REST API (Postgres + pgvector + BM25).
+ * Implements the generic MemoryProvider interface for framework integration,
+ * plus brain-specific methods for advanced usage.
+ */
+export class BrainClient implements MemoryProvider {
+  readonly id = 'brain'
+  readonly name = 'Lunar Brain'
+
+  private url: string
+  private apiKey?: string
+  private timeoutMs: number
+
+  constructor(options: BrainClientOptions) {
+    // Normalize URL: remove trailing slash
+    this.url = options.url.replace(/\/+$/, '')
+    this.apiKey = options.apiKey
+    this.timeoutMs = options.timeoutMs ?? 10_000
+  }
+
+  // ─── MemoryProvider interface ──────────────────────────────────────
+
+  async init(): Promise<void> {
+    const result = await this.health()
+    if (!result.ok) {
+      throw new Error(`Brain health check failed: ${result.error}`)
+    }
+    log.info({ url: this.url }, 'Brain memory provider initialized')
+  }
+
+  async destroy(): Promise<void> {
+    // No persistent connections to clean up
+  }
+
+  /**
+   * Agent instructions — injected into system prompt.
+   * Tells the agent what the brain is, how to query it, and when to save.
+   */
+  agentInstructions(): string {
+    const fence = '`' + '`' + '`'
+    return [
+      '## Memory — Long-term Knowledge (Brain API)',
+      '',
+      'You have access to a Brain API for persistent semantic memory.',
+      'The system auto-recalls relevant memories before each query (see "Memory Context" below if present).',
+      '',
+      '### Direct access (for specific queries)',
+      '',
+      '**Recall** — search across facts, entities, relations, episodes:',
+      fence + 'bash',
+      "curl -s -X POST $BRAIN_URL/recall -H 'Content-Type: application/json' \\",
+      '  -d \'{"query": "topic or question", "limit": 5}\'',
+      fence,
+      '',
+      '**Save fact** — store decisions, learnings, observations:',
+      fence + 'bash',
+      "curl -s -X POST $BRAIN_URL/facts -H 'Content-Type: application/json' \\",
+      '  -d \'{"content": "...", "domain": "work|personal|...", "category": "decision|learning|...", "importance": 7, "tags": ["..."], "sessionDate": "YYYY-MM-DD"}\'',
+      fence,
+      '',
+      '**Entities** — knowledge graph nodes (people, projects, orgs):',
+      fence + 'bash',
+      'curl -s $BRAIN_URL/entities?limit=10          # list',
+      'curl -s $BRAIN_URL/entities/<id>              # entity + relations + facts',
+      fence,
+      '',
+      '### When to use',
+      '- **Recall**: before answering about people, projects, decisions, preferences, history',
+      '- **Save**: after important decisions, learnings, milestones, or configuration changes',
+      '- Auto-recalled context (if any) appears at the end of the system prompt',
+    ].join('\n')
+  }
+
+  /**
+   * Semantic recall — searches across facts, entities, relations, episodes, summaries.
+   */
+  async recall(query: string, options?: SearchOptions): Promise<MemoryResult[]> {
+    const body: Record<string, unknown> = {
+      query,
+      limit: options?.limit ?? 10,
+    }
+
+    if (options?.minScore !== undefined) body.minScore = options.minScore
+    if (options?.category) body.category = options.category
+    if (options?.tags?.length) body.tags = options.tags
+
+    const response = await this.fetch('/recall', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain recall failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as BrainPaginatedResponse<BrainRecallResult>
+
+    return result.data.map((r) => this.toMemoryResult(r))
+  }
+
+  /**
+   * Save facts to brain.
+   * Uses the generic Fact interface. For brain-specific fields (domain, entityId, etc.),
+   * use saveFact() instead.
+   */
+  async save(facts: Fact[]): Promise<string[]> {
+    const ids: string[] = []
+    for (const fact of facts) {
+      const id = await this.saveFact({
+        content: fact.content,
+        category: fact.category,
+        domain: fact.domain ?? 'general',
+        tags: fact.tags,
+        importance: fact.importance ?? 5,
+        source: fact.source,
+        timestamp: fact.timestamp,
+        sessionDate: (fact as BrainFact).sessionDate,
+        episodeId: (fact as BrainFact).episodeId,
+      })
+      ids.push(id)
+    }
+    return ids
+  }
+
+  async health(): Promise<{ ok: boolean; error?: string }> {
+    try {
+      const response = await this.fetch('/health', { method: 'GET' })
+      if (!response.ok) {
+        return { ok: false, error: `HTTP ${response.status}` }
+      }
+      const data = (await response.json()) as { status: string }
+      return { ok: data.status === 'ok', error: data.status !== 'ok' ? 'Unhealthy' : undefined }
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  // ─── Brain-specific methods ────────────────────────────────────────
+
+  /**
+   * Save a single fact with brain-specific fields.
+   * Returns the created fact ID.
+   */
+  async saveFact(fact: BrainFact): Promise<string> {
+    const body: Record<string, unknown> = {
+      content: fact.content,
+    }
+
+    if (fact.entityId) body.entityId = fact.entityId
+    if (fact.domain) body.domain = fact.domain
+    if (fact.category) body.category = fact.category
+    if (fact.confidence !== undefined) body.confidence = fact.confidence
+    if (fact.importance !== undefined) body.importance = fact.importance
+    if (fact.tags?.length) body.tags = fact.tags
+    if (fact.sessionDate) body.sessionDate = fact.sessionDate
+    if (fact.decayImmune !== undefined) body.decayImmune = fact.decayImmune
+    if (fact.episodeId) body.episodeId = fact.episodeId
+
+    const response = await this.fetch('/facts', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain saveFact failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as { id: string }
+    return result.id
+  }
+
+  /**
+   * Create a brain entity.
+   * Returns the created entity ID.
+   */
+  async createEntity(entity: BrainEntity): Promise<string> {
+    const response = await this.fetch('/entities', {
+      method: 'POST',
+      body: JSON.stringify(entity),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain createEntity failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as { id: string }
+    return result.id
+  }
+
+  /**
+   * Create a relation between two entities.
+   * Returns the created relation ID.
+   */
+  async createRelation(relation: BrainRelation): Promise<string> {
+    const response = await this.fetch('/relations', {
+      method: 'POST',
+      body: JSON.stringify(relation),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain createRelation failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as { id: string }
+    return result.id
+  }
+
+  /**
+   * Run the extraction pipeline on a conversation.
+   * Extracts facts, entities, relations and creates an episode automatically.
+   */
+  async extractPipeline(
+    conversation: string,
+    channel?: string,
+    sessionDate?: string,
+  ): Promise<{ facts: number; entities: number; relations: number; episodeId?: string }> {
+    const response = await this.fetch('/pipeline/extract', {
+      method: 'POST',
+      body: JSON.stringify({
+        conversation,
+        channel,
+        agentId: 'lunar',
+        sessionDate,
+      }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain pipeline failed (${response.status}): ${text}`)
+    }
+
+    return (await response.json()) as {
+      facts: number
+      entities: number
+      relations: number
+      episodeId?: string
+    }
+  }
+
+  /**
+   * Get an entity with its full graph (relations + facts).
+   */
+  async getEntity(id: string): Promise<Record<string, unknown> | null> {
+    const response = await this.fetch(`/entities/${id}`, { method: 'GET' })
+    if (response.status === 404) return null
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain getEntity failed (${response.status}): ${text}`)
+    }
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  /**
+   * List entities with optional filters.
+   */
+  async listEntities(filters?: {
+    type?: string
+    search?: string
+    limit?: number
+  }): Promise<Record<string, unknown>[]> {
+    const params = new URLSearchParams()
+    if (filters?.type) params.set('type', filters.type)
+    if (filters?.search) params.set('search', filters.search)
+    if (filters?.limit) params.set('limit', String(filters.limit))
+
+    const qs = params.toString()
+    const response = await this.fetch(`/entities${qs ? `?${qs}` : ''}`, { method: 'GET' })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain listEntities failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as { data?: Record<string, unknown>[] }
+    return result.data ?? (result as unknown as Record<string, unknown>[])
+  }
+
+  /**
+   * Graph traversal — BFS multi-hop from an entity.
+   */
+  async graphTraverse(entityId: string, maxHops?: number): Promise<Record<string, unknown>> {
+    const response = await this.fetch('/graph/traverse', {
+      method: 'POST',
+      body: JSON.stringify({ entityId, maxHops: maxHops ?? 2 }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain graphTraverse failed (${response.status}): ${text}`)
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  /**
+   * Temporal query — what changed since a date.
+   */
+  async graphTemporal(since: string): Promise<Record<string, unknown>> {
+    const response = await this.fetch('/graph/temporal', {
+      method: 'POST',
+      body: JSON.stringify({ since }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain graphTemporal failed (${response.status}): ${text}`)
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  /**
+   * Query facts by direct filters (not semantic recall).
+   * Used by diary recall to get facts by date + domain.
+   */
+  async queryFacts(filters: {
+    sessionDate?: string
+    domain?: string
+    category?: string
+    episodeId?: string
+    limit?: number
+  }): Promise<
+    Array<{
+      id: string
+      content: string
+      domain: string
+      category: string
+      episodeId?: string
+      sessionDate?: string
+      importance: number
+      createdAt: string
+    }>
+  > {
+    const params = new URLSearchParams()
+    if (filters.sessionDate) params.set('sessionDate', filters.sessionDate)
+    if (filters.domain) params.set('domain', filters.domain)
+    if (filters.category) params.set('category', filters.category)
+    if (filters.episodeId) params.set('episodeId', filters.episodeId)
+    if (filters.limit) params.set('limit', String(filters.limit))
+
+    const response = await this.fetch(`/facts?${params}`, { method: 'GET' })
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain queryFacts failed (${response.status}): ${text}`)
+    }
+
+    const result = (await response.json()) as {
+      data: Array<Record<string, unknown>>
+      count: number
+    }
+    return result.data as any
+  }
+
+  // ─── Episode management ─────────────────────────────────────────────
+
+  /**
+   * Get or create an episode for a session date + channel.
+   * If an episode already exists for today+channel, returns it.
+   * Otherwise creates a new one.
+   */
+  async getOrCreateEpisode(
+    sessionDate: string,
+    channel?: string,
+    agentId = 'lunar',
+  ): Promise<BrainEpisode> {
+    // Try to find existing episode for this date+channel
+    const params = new URLSearchParams({ date: sessionDate })
+    if (channel) params.set('channel', channel)
+    params.set('limit', '1')
+
+    const response = await this.fetch(`/episodes?${params}`, { method: 'GET' })
+    if (response.ok) {
+      const result = (await response.json()) as { data: BrainEpisode[]; count: number }
+      if (result.data.length > 0) {
+        log.debug({ episodeId: result.data[0].id, sessionDate, channel }, 'Existing episode found')
+        return result.data[0]
+      }
+    }
+
+    // Create new episode
+    const createResponse = await this.fetch('/episodes', {
+      method: 'POST',
+      body: JSON.stringify({
+        sessionDate,
+        channel: channel || null,
+        agentId,
+        summary: '',
+      }),
+    })
+
+    if (!createResponse.ok) {
+      const text = await createResponse.text()
+      throw new Error(`Brain createEpisode failed (${createResponse.status}): ${text}`)
+    }
+
+    const episode = (await createResponse.json()) as BrainEpisode
+    log.info({ episodeId: episode.id, sessionDate, channel }, 'New episode created')
+    return episode
+  }
+
+  /**
+   * Update an episode (e.g., add factIds, summary, topics at session close).
+   */
+  async updateEpisode(
+    id: string,
+    data: Partial<
+      Pick<
+        BrainEpisode,
+        | 'factIds'
+        | 'entityIds'
+        | 'summary'
+        | 'keyOutcomes'
+        | 'topics'
+        | 'moodEnergy'
+        | 'messageCount'
+        | 'importance'
+      >
+    >,
+  ): Promise<BrainEpisode> {
+    const response = await this.fetch(`/episodes/${id}`, {
+      method: 'PATCH',
+      body: JSON.stringify(data),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Brain updateEpisode failed (${response.status}): ${text}`)
+    }
+
+    return (await response.json()) as BrainEpisode
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────
+
+  private async fetch(path: string, init: RequestInit): Promise<Response> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`
+    }
+
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+
+    try {
+      return await fetch(`${this.url}${path}`, {
+        ...init,
+        headers: { ...headers, ...(init.headers as Record<string, string>) },
+        signal: controller.signal,
+      })
+    } catch (err) {
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw new Error(`Brain request timed out after ${this.timeoutMs}ms: ${path}`)
+      }
+      throw err
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  /**
+   * Map a brain recall result to the generic MemoryResult format.
+   * Brain API returns: { source, id, score, data: { ...details } }
+   */
+  private toMemoryResult(r: BrainRecallResult): MemoryResult {
+    const d = r.data
+
+    // Extract the best content text based on result source type
+    let content: string
+    switch (r.source) {
+      case 'fact':
+        content = d.content ?? ''
+        break
+      case 'entity':
+        content = `[Entity: ${d.name ?? 'unknown'}]`
+        break
+      case 'relation':
+        content = d.description ?? `[Relation: ${d.relationType ?? r.source}]`
+        break
+      case 'episode':
+        content = d.summary ?? ''
+        if (d.keyOutcomes?.length) {
+          content += ` | Outcomes: ${d.keyOutcomes.join(', ')}`
+        }
+        break
+      case 'summary':
+        content = d.summary ?? ''
+        break
+      default:
+        content = d.content ?? d.summary ?? d.name ?? ''
+    }
+
+    return {
+      content,
+      score: r.score,
+      metadata: {
+        type: r.source,
+        id: r.id,
+        domain: d.domain,
+        category: d.category,
+        importance: d.importance,
+        entityId: d.entityId,
+        tags: d.tags,
+        sessionDate: d.sessionDate,
+      },
+      storedAt: d.createdAt ? new Date(d.createdAt) : undefined,
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { BrainClientOptions, BrainEntity, BrainFact, BrainRelation } from './client'
+export { BrainClient } from './client'