@onmars/lunar-memory-engram 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-engram
+
+Engram memory provider (MCP-based local memory) 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,32 @@
+{
+  "name": "@onmars/lunar-memory-engram",
+  "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",
+    "@onmars/lunar-mcp": "0.1.0"
+  },
+  "description": "Engram memory provider for Lunar (MCP-based local memory)",
+  "author": "onMars Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onmars-tech/lunar",
+    "directory": "packages/memory-engram"
+  },
+  "homepage": "https://github.com/onmars-tech/lunar",
+  "bugs": "https://github.com/onmars-tech/lunar/issues",
+  "keywords": ["lunar", "memory", "engram", "mcp", "bun"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"bun": ">=1.2"
+}
+}

package/src/__tests__/adapter.test.ts

@@ -0,0 +1,495 @@
+/**
+ * EngramMemoryAdapter test suite
+ *
+ * Tests the adapter using the mock MCP server from @onmars/lunar-mcp.
+ * Validates: init, recall, save, onSessionEnd, health, agentInstructions.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { resolve } from 'node:path'
+import { MCPConnection } from '@onmars/lunar-mcp'
+import { EngramMemoryAdapter } from '../lib/adapter'
+
+const MOCK_SERVER = resolve(
+  import.meta.dir,
+  '../../..',
+  'mcp',
+  'src',
+  '__tests__',
+  'mock-mcp-server.ts',
+)
+const BUN = process.env.HOME + '/.bun/bin/bun'
+
+describe('EngramMemoryAdapter', () => {
+  let conn: MCPConnection
+  let adapter: EngramMemoryAdapter
+
+  beforeEach(async () => {
+    conn = new MCPConnection({
+      id: 'engram-test',
+      command: `${BUN} run ${MOCK_SERVER}`,
+      timeoutMs: 5000,
+      autoRestart: false,
+    })
+    await conn.connect()
+    adapter = new EngramMemoryAdapter(conn, { project: 'test-project' })
+  })
+
+  afterEach(() => {
+    conn.kill()
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Identity
+  // ═══════════════════════════════════════════════════════════
+
+  test('has correct id and name', () => {
+    expect(adapter.id).toBe('engram')
+    expect(adapter.name).toBe('Engram Session Memory')
+  })
+
+  test('has recall and session traits', () => {
+    expect(adapter.traits.has('recall')).toBe(true)
+    expect(adapter.traits.has('session')).toBe(true)
+    expect(adapter.traits.has('semantic')).toBe(false)
+    expect(adapter.traits.has('graph')).toBe(false)
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Init
+  // ═══════════════════════════════════════════════════════════
+
+  test('init starts a session via MCP', async () => {
+    await adapter.init()
+    // After init, connection should still be healthy (session was started)
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  test('init throws when connection is not ready', async () => {
+    conn.kill()
+    const deadAdapter = new EngramMemoryAdapter(conn)
+    expect(deadAdapter.init()).rejects.toThrow('not ready')
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Recall
+  // ═══════════════════════════════════════════════════════════
+
+  test('recall returns search results mapped to MemoryResult', async () => {
+    const results = await adapter.recall('auth')
+    expect(results.length).toBeGreaterThan(0)
+
+    const searchResults = results.filter((r) => r.source === 'engram:search')
+    expect(searchResults.length).toBe(2) // Mock returns 2 results
+
+    expect(searchResults[0].content).toContain('Auth middleware')
+    expect(searchResults[0].score).toBe(0.9)
+    expect(searchResults[0].metadata?.title).toBe('Auth middleware')
+  })
+
+  test('recall includes context results when enabled', async () => {
+    const results = await adapter.recall('anything')
+    const contextResults = results.filter((r) => r.source === 'engram:context')
+    expect(contextResults.length).toBe(1)
+    expect(contextResults[0].content).toContain('MCP integration')
+  })
+
+  test('recall without context when disabled', async () => {
+    const noCtxAdapter = new EngramMemoryAdapter(conn, { includeContext: false })
+    const results = await noCtxAdapter.recall('auth')
+    const contextResults = results.filter((r) => r.source === 'engram:context')
+    expect(contextResults.length).toBe(0)
+  })
+
+  test('recall with custom limit', async () => {
+    const results = await adapter.recall('auth', { limit: 5 })
+    expect(results.length).toBeGreaterThan(0)
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Save
+  // ═══════════════════════════════════════════════════════════
+
+  test('save sends facts as mem_save calls', async () => {
+    await adapter.init()
+    // save() should complete without error; verify connection stays healthy
+    await adapter.save([
+      { content: 'Authentication uses JWT tokens', title: 'Auth pattern', type: 'decision' },
+      { content: 'PostgreSQL for persistence', title: 'DB choice', type: 'architecture' },
+    ])
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  test('save generates title from content when missing', async () => {
+    // When no title is provided, save() should use content.slice(0, 60) as title
+    // This should complete without error on the mock server
+    await adapter.save([{ content: 'Some important observation without a title field' }])
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Session end
+  // ═══════════════════════════════════════════════════════════
+
+  test('onSessionEnd sends summary and ends session', async () => {
+    await adapter.init()
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'Build the auth system' }],
+      sessionSummary: 'Implemented JWT auth with refresh tokens',
+      topics: ['auth', 'security'],
+    })
+    // Session ID should be cleared; health should still be ok
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  test('onSessionEnd builds summary from messages when none provided', async () => {
+    await adapter.init()
+    await adapter.onSessionEnd({
+      messages: [
+        { role: 'user', content: 'Fix the login bug' },
+        { role: 'assistant', content: 'Fixed by updating the JWT validation' },
+        { role: 'user', content: 'Now add rate limiting' },
+      ],
+      topics: ['auth', 'security'],
+    })
+    // Verify the operation completed and connection is still healthy
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  test('onSessionEnd is no-op without init', async () => {
+    // No init => no sessionId => onSessionEnd returns early
+    // Verify recall still works (adapter is not in broken state)
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+    })
+    const results = await adapter.recall('test')
+    expect(results.length).toBeGreaterThan(0)
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Health
+  // ═══════════════════════════════════════════════════════════
+
+  test('health returns ok when connected', async () => {
+    const health = await adapter.health()
+    expect(health.ok).toBe(true)
+  })
+
+  test('health returns error when disconnected', async () => {
+    conn.kill()
+    const health = await adapter.health()
+    expect(health.ok).toBe(false)
+    expect(health.error).toContain('disconnected')
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Agent instructions
+  // ═══════════════════════════════════════════════════════════
+
+  test('agentInstructions includes project name', () => {
+    const instructions = adapter.agentInstructions()
+    expect(instructions).toContain('test-project')
+    expect(instructions).toContain('Engram')
+    expect(instructions).toContain('mem_search')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// Unit tests with mocked MCP connection (no subprocess)
+// ═══════════════════════════════════════════════════════════════════
+
+describe('EngramMemoryAdapter — unit (mocked connection)', () => {
+  /** Create a fake MCPConnection with controllable callTool and state */
+  function mockConnection(state: string = 'ready') {
+    const calls: Array<{ tool: string; args: any }> = []
+    return {
+      conn: {
+        state,
+        callTool: async (tool: string, args: any) => {
+          calls.push({ tool, args })
+          return { content: [{ type: 'text', text: '{}' }] }
+        },
+      } as any,
+      calls,
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // onSessionEnd — detailed unit tests
+  // ═══════════════════════════════════════════════════════════
+
+  test('onSessionEnd calls mem_session_summary then mem_session_end with provided summary', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn, { project: 'unit-test' })
+
+    // Must init first to get a sessionId
+    await adapter.init()
+    const sessionId = (adapter as any).sessionId
+    expect(sessionId).toBeTruthy()
+
+    calls.length = 0 // clear init calls
+
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'Hello' }],
+      sessionSummary: 'We discussed greetings',
+      topics: ['greetings'],
+    })
+
+    // Should have called mem_session_summary with the provided summary
+    const summaryCall = calls.find((c) => c.tool === 'mem_session_summary')
+    expect(summaryCall).toBeTruthy()
+    expect(summaryCall!.args.summary).toBe('We discussed greetings')
+    expect(summaryCall!.args.session_id).toBe(sessionId)
+
+    // Should have called mem_session_end
+    const endCall = calls.find((c) => c.tool === 'mem_session_end')
+    expect(endCall).toBeTruthy()
+    expect(endCall!.args.id).toBe(sessionId)
+    expect(endCall!.args.summary).toBe('We discussed greetings')
+  })
+
+  test('onSessionEnd builds summary from messages when sessionSummary is not provided', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn, { project: 'unit-test' })
+
+    await adapter.init()
+    calls.length = 0
+
+    await adapter.onSessionEnd({
+      messages: [
+        { role: 'user', content: 'Fix the login bug' },
+        { role: 'assistant', content: 'I fixed it by updating the JWT validation' },
+        { role: 'user', content: 'Now add rate limiting' },
+      ],
+      topics: ['auth', 'security'],
+    })
+
+    const summaryCall = calls.find((c) => c.tool === 'mem_session_summary')
+    expect(summaryCall).toBeTruthy()
+    // The built summary should contain user topics and messages
+    expect(summaryCall!.args.summary).toContain('auth, security')
+    expect(summaryCall!.args.summary).toContain('Fix the login bug')
+    expect(summaryCall!.args.summary).toContain('Now add rate limiting')
+  })
+
+  test('onSessionEnd clears sessionId after completion', async () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+
+    await adapter.init()
+    expect((adapter as any).sessionId).toBeTruthy()
+
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'done' }],
+      sessionSummary: 'Session complete',
+    })
+
+    expect((adapter as any).sessionId).toBeNull()
+  })
+
+  test('onSessionEnd is no-op when no sessionId (not initialized)', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+
+    // Do NOT call init — no sessionId
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'Should be skipped',
+    })
+
+    // Should not have called any MCP tools
+    expect(calls.length).toBe(0)
+  })
+
+  test('onSessionEnd handles MCP call failures gracefully (catch blocks)', async () => {
+    const callCount = { summary: 0, end: 0 }
+    const conn = {
+      state: 'ready',
+      callTool: async (tool: string, args: any) => {
+        if (tool === 'mem_session_start') return { content: [] }
+        if (tool === 'mem_session_summary') {
+          callCount.summary++
+          throw new Error('MCP summary failed')
+        }
+        if (tool === 'mem_session_end') {
+          callCount.end++
+          throw new Error('MCP end failed')
+        }
+        return { content: [] }
+      },
+    } as any
+    const adapter = new EngramMemoryAdapter(conn)
+
+    await adapter.init()
+
+    // Should NOT throw even though MCP calls fail (both have .catch(() => {}))
+    await adapter.onSessionEnd({
+      messages: [{ role: 'user', content: 'test' }],
+      sessionSummary: 'test summary',
+    })
+
+    expect(callCount.summary).toBe(1)
+    expect(callCount.end).toBe(1)
+    // sessionId should still be cleared
+    expect((adapter as any).sessionId).toBeNull()
+  })
+
+  test('onSessionEnd sends "Session ended" as default summary to mem_session_end', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+
+    await adapter.init()
+    calls.length = 0
+
+    // Empty messages, no sessionSummary, no topics → buildSummaryFromMessages returns ''
+    await adapter.onSessionEnd({
+      messages: [],
+    })
+
+    // mem_session_summary should NOT have been called (summary is empty)
+    const summaryCall = calls.find((c) => c.tool === 'mem_session_summary')
+    expect(summaryCall).toBeUndefined()
+
+    // mem_session_end should use 'Session ended' as fallback
+    const endCall = calls.find((c) => c.tool === 'mem_session_end')
+    expect(endCall).toBeTruthy()
+    expect(endCall!.args.summary).toBe('Session ended')
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // save — unit tests
+  // ═══════════════════════════════════════════════════════════
+
+  test('save calls mem_save with correct fact type mapping', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn, { project: 'unit-test' })
+
+    await adapter.init()
+    calls.length = 0
+
+    await adapter.save([
+      { content: 'Decision content', title: 'My Decision', type: 'decision' },
+      { content: 'Bug was fixed', title: 'Bug Fix', type: 'bugfix' },
+      { content: 'Unknown type', title: 'Unknown', type: 'unknown_type' },
+      { content: 'No type', title: 'No Type' },
+    ])
+
+    expect(calls).toHaveLength(4)
+    expect(calls[0].args.type).toBe('decision')
+    expect(calls[1].args.type).toBe('bugfix')
+    expect(calls[2].args.type).toBe('discovery') // unknown maps to discovery
+    expect(calls[3].args.type).toBe('discovery') // no type maps to discovery
+  })
+
+  test('save includes session_id when session is active', async () => {
+    const { conn, calls } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn, { project: 'unit-test' })
+
+    await adapter.init()
+    const sessionId = (adapter as any).sessionId
+    calls.length = 0
+
+    await adapter.save([{ content: 'Test fact', title: 'Test' }])
+
+    expect(calls[0].args.session_id).toBe(sessionId)
+    expect(calls[0].args.project).toBe('unit-test')
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // destroy — unit tests
+  // ═══════════════════════════════════════════════════════════
+
+  test('destroy clears sessionId', async () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+
+    await adapter.init()
+    expect((adapter as any).sessionId).toBeTruthy()
+
+    await adapter.destroy()
+    expect((adapter as any).sessionId).toBeNull()
+  })
+
+  // ═══════════════════════════════════════════════════════════
+  // Private helpers — unit tests
+  // ═══════════════════════════════════════════════════════════
+
+  test('extractText extracts text content blocks', () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+    const extract = (adapter as any).extractText.bind(adapter)
+
+    expect(
+      extract({
+        content: [
+          { type: 'text', text: 'Hello' },
+          { type: 'text', text: 'World' },
+        ],
+      }),
+    ).toBe('Hello\nWorld')
+    expect(extract({ content: [{ type: 'image', url: 'x' }] })).toBe('')
+    expect(extract({})).toBe('')
+    expect(extract(null)).toBe('')
+  })
+
+  test('mapFactType maps known types and defaults to discovery', () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+    const mapType = (adapter as any).mapFactType.bind(adapter)
+
+    expect(mapType('decision')).toBe('decision')
+    expect(mapType('achievement')).toBe('discovery')
+    expect(mapType('learning')).toBe('learning')
+    expect(mapType('observation')).toBe('pattern')
+    expect(mapType('bugfix')).toBe('bugfix')
+    expect(mapType('architecture')).toBe('architecture')
+    expect(mapType('config')).toBe('config')
+    expect(mapType('unknown')).toBe('discovery')
+    expect(mapType(undefined)).toBe('discovery')
+  })
+
+  test('buildSummaryFromMessages handles more than 5 user messages', () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+    const build = (adapter as any).buildSummaryFromMessages.bind(adapter)
+
+    const context = {
+      messages: Array.from({ length: 8 }, (_, i) => ({
+        role: 'user',
+        content: `Message ${i + 1}`,
+      })),
+      topics: ['topic1'],
+    }
+
+    const summary = build(context)
+    expect(summary).toContain('Message 1')
+    expect(summary).toContain('Message 5')
+    expect(summary).toContain('and 3 more')
+    expect(summary).not.toContain('Message 6')
+  })
+
+  test('buildSummaryFromMessages returns empty string with no user messages', () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+    const build = (adapter as any).buildSummaryFromMessages.bind(adapter)
+
+    expect(build({ messages: [], topics: ['auth'] })).toBe('')
+    expect(build({ messages: [{ role: 'assistant', content: 'only assistant' }] })).toBe('')
+  })
+
+  test('buildSummaryFromMessages uses "various topics" when no topics provided', () => {
+    const { conn } = mockConnection()
+    const adapter = new EngramMemoryAdapter(conn)
+    const build = (adapter as any).buildSummaryFromMessages.bind(adapter)
+
+    const summary = build({
+      messages: [{ role: 'user', content: 'Some question' }],
+    })
+    expect(summary).toContain('various topics')
+  })
+})

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @onmars/lunar-memory-engram — Engram session memory provider for Lunar
+ *
+ * Wraps Engram's MCP tools as a standard MemoryProvider.
+ * Requires an MCPConnection to an Engram server.
+ *
+ * @example
+ * ```typescript
+ * import { MCPConnection } from '@onmars/lunar-mcp'
+ * import { EngramMemoryAdapter } from '@onmars/lunar-memory-engram'
+ *
+ * const conn = new MCPConnection({ id: 'engram', command: 'engram mcp' })
+ * await conn.connect()
+ *
+ * const engram = new EngramMemoryAdapter(conn, { project: 'my-project' })
+ * await engram.init()
+ *
+ * const results = await engram.recall('auth middleware')
+ * ```
+ */
+
+export type {
+  EngramAdapterConfig,
+  Fact,
+  MemoryResult,
+  MemoryTrait,
+  SessionContext,
+} from './lib/adapter'
+export { EngramMemoryAdapter } from './lib/adapter'

package/src/lib/adapter.ts

@@ -0,0 +1,268 @@
+/**
+ * EngramMemoryAdapter — Wraps an MCP connection to Engram as a MemoryProvider
+ *
+ * Maps MemoryProvider interface to Engram MCP tools:
+ *   recall()        → mem_search + mem_context (parallel)
+ *   onSessionEnd()  → mem_session_summary + mem_session_end
+ *   init()          → mem_session_start
+ *   save()          → mem_save
+ *   health()        → connection state
+ *
+ * Traits: recall, session
+ */
+
+import type { MCPConnection } from '@onmars/lunar-mcp'
+
+// ════════════════════════════════════════════════════════════
+// Types
+// ════════════════════════════════════════════════════════════
+
+export type MemoryTrait = 'recall' | 'session' | 'semantic' | 'graph' | 'file-based' | 'extraction'
+
+export interface MemoryResult {
+  source: string
+  content: string
+  score: number
+  metadata?: Record<string, unknown>
+}
+
+export interface SessionContext {
+  messages: Array<{ role: string; content: string }>
+  sessionSummary?: string
+  topics?: string[]
+}
+
+export interface Fact {
+  content: string
+  title?: string
+  type?: string
+  category?: string
+}
+
+export interface EngramAdapterConfig {
+  project?: string
+  searchLimit?: number
+  includeContext?: boolean
+}
+
+// ════════════════════════════════════════════════════════════
+// Adapter
+// ════════════════════════════════════════════════════════════
+
+export class EngramMemoryAdapter {
+  readonly id = 'engram'
+  readonly name = 'Engram Session Memory'
+  readonly traits = new Set<MemoryTrait>(['recall', 'session'])
+
+  private connection: MCPConnection
+  private config: Required<EngramAdapterConfig>
+  private sessionId: string | null = null
+
+  constructor(connection: MCPConnection, config: EngramAdapterConfig = {}) {
+    this.connection = connection
+    this.config = {
+      project: config.project || 'default',
+      searchLimit: config.searchLimit || 10,
+      includeContext: config.includeContext ?? true,
+    }
+  }
+
+  async init(): Promise<void> {
+    if (this.connection.state !== 'ready') {
+      throw new Error('Engram MCP connection is not ready')
+    }
+    this.sessionId = `lunar-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    await this.connection.callTool('mem_session_start', {
+      id: this.sessionId,
+      project: this.config.project,
+      directory: process.cwd(),
+    })
+  }
+
+  async destroy(): Promise<void> {
+    this.sessionId = null
+  }
+
+  async recall(query: string, options?: { limit?: number }): Promise<MemoryResult[]> {
+    const limit = options?.limit || this.config.searchLimit
+    const results: MemoryResult[] = []
+    const promises: Promise<void>[] = []
+
+    // 1. FTS5 search
+    promises.push(
+      this.connection
+        .callTool('mem_search', {
+          query,
+          limit,
+          project: this.config.project,
+        })
+        .then((result) => {
+          const text = this.extractText(result)
+          const parsed = this.tryParseJson(text)
+          if (Array.isArray(parsed)) {
+            for (const item of parsed) {
+              results.push({
+                source: 'engram:search',
+                content: this.formatObservation(item),
+                score: item.score ?? 0.5,
+                metadata: {
+                  id: item.id,
+                  type: item.type,
+                  title: item.title,
+                  sessionId: item.session_id,
+                },
+              })
+            }
+          } else if (typeof text === 'string' && text.trim()) {
+            results.push({ source: 'engram:search', content: text, score: 0.5 })
+          }
+        })
+        .catch(() => {}),
+    )
+
+    // 2. Recent context
+    if (this.config.includeContext) {
+      promises.push(
+        this.connection
+          .callTool('mem_context', {
+            project: this.config.project,
+          })
+          .then((result) => {
+            const text = this.extractText(result)
+            if (text?.trim()) {
+              results.push({
+                source: 'engram:context',
+                content: text,
+                score: 0.6,
+                metadata: { type: 'session_context' },
+              })
+            }
+          })
+          .catch(() => {}),
+      )
+    }
+
+    await Promise.allSettled(promises)
+    return results
+  }
+
+  async save(facts: Fact[]): Promise<void> {
+    for (const fact of facts) {
+      await this.connection.callTool('mem_save', {
+        title: fact.title || fact.content.slice(0, 60),
+        content: fact.content,
+        type: this.mapFactType(fact.type || fact.category),
+        project: this.config.project,
+        ...(this.sessionId && { session_id: this.sessionId }),
+      })
+    }
+  }
+
+  async onSessionEnd(context: SessionContext): Promise<void> {
+    if (!this.sessionId) return
+
+    const summary = context.sessionSummary || this.buildSummaryFromMessages(context)
+
+    if (summary) {
+      await this.connection
+        .callTool('mem_session_summary', {
+          summary,
+          session_id: this.sessionId,
+        })
+        .catch(() => {})
+    }
+
+    await this.connection
+      .callTool('mem_session_end', {
+        id: this.sessionId,
+        summary: summary || 'Session ended',
+      })
+      .catch(() => {})
+
+    this.sessionId = null
+  }
+
+  async health(): Promise<{ ok: boolean; error?: string }> {
+    if (this.connection.state !== 'ready') {
+      return { ok: false, error: `MCP connection state: ${this.connection.state}` }
+    }
+    return { ok: true }
+  }
+
+  agentInstructions(): string {
+    return [
+      '## Engram Session Memory',
+      '',
+      'Engram provides session-level memory with full-text search.',
+      'Memory is automatically recalled before each query.',
+      '',
+      'Available MCP tools (if direct access is enabled):',
+      '- `mem_search` — Search across all memories (FTS5)',
+      '- `mem_save` — Save an observation (decision, bugfix, pattern, etc.)',
+      '- `mem_context` — Get recent context from previous sessions',
+      '- `mem_timeline` — Chronological context around a specific observation',
+      '- `mem_get_observation` — Get full content of a specific memory',
+      '',
+      `Project: ${this.config.project}`,
+    ].join('\n')
+  }
+
+  // ═════════════════════════════════════════════════════
+  // Private helpers
+  // ═════════════════════════════════════════════════════
+
+  private extractText(result: unknown): string {
+    const r = result as { content?: Array<{ type: string; text?: string }> }
+    if (!r?.content) return ''
+    return r.content
+      .filter((c) => c.type === 'text' && c.text)
+      .map((c) => c.text!)
+      .join('\n')
+  }
+
+  private tryParseJson(text: string): unknown {
+    try {
+      return JSON.parse(text)
+    } catch {
+      return null
+    }
+  }
+
+  private formatObservation(obs: Record<string, unknown>): string {
+    const parts: string[] = []
+    if (obs.title) parts.push(`[${obs.type || 'observation'}] ${obs.title}`)
+    if (obs.content) parts.push(String(obs.content))
+    return parts.join('\n') || JSON.stringify(obs)
+  }
+
+  private mapFactType(type?: string): string {
+    const map: Record<string, string> = {
+      decision: 'decision',
+      achievement: 'discovery',
+      learning: 'learning',
+      observation: 'pattern',
+      bugfix: 'bugfix',
+      architecture: 'architecture',
+      config: 'config',
+    }
+    return type ? map[type] || 'discovery' : 'discovery'
+  }
+
+  private buildSummaryFromMessages(context: SessionContext): string {
+    const userMsgs = context.messages
+      .filter((m) => m.role === 'user')
+      .map((m) => m.content.slice(0, 100))
+    if (!userMsgs.length) return ''
+    const topics = context.topics?.join(', ') || 'various topics'
+    return [
+      `## Goal`,
+      `User discussed: ${topics}`,
+      '',
+      `## Topics covered`,
+      ...userMsgs.slice(0, 5).map((m) => `- ${m}`),
+      userMsgs.length > 5 ? `- ... and ${userMsgs.length - 5} more` : '',
+    ]
+      .filter(Boolean)
+      .join('\n')
+  }
+}