@kaleidorg/mind 0.1.0 → 0.3.0

package/src/lsps1/contract.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import {
+  LSPS1_TOOLS,
+  LSPS1_SPEND_TOOLS,
+  isLsps1SpendTool,
+  getLsps1Tool,
+  bindLsps1Tools,
+  type Lsps1Handler,
+} from './contract.js';
+
+describe('LSPS1_TOOLS — shape invariants', () => {
+  it('exposes the expected tool names', () => {
+    expect(LSPS1_TOOLS.map((t) => t.name)).toEqual([
+      'lsp_get_info',
+      'lsp_get_network_info',
+      'lsp_estimate_fees',
+      'lsp_create_order',
+      'lsp_get_order',
+    ]);
+  });
+
+  it('every tool has an object parameters schema', () => {
+    for (const t of LSPS1_TOOLS) {
+      expect((t.parameters as any)?.type).toBe('object');
+    }
+  });
+
+  it('aligns spend ↔ requiresConfirmation', () => {
+    for (const t of LSPS1_TOOLS) {
+      expect(!!t.spend).toBe(!!t.requiresConfirmation);
+    }
+  });
+
+  it('marks only lsp_create_order as spend', () => {
+    expect([...LSPS1_SPEND_TOOLS]).toEqual(['lsp_create_order']);
+    expect(isLsps1SpendTool('lsp_create_order')).toBe(true);
+    expect(isLsps1SpendTool('lsp_get_info')).toBe(false);
+  });
+
+  it('getLsps1Tool returns by name', () => {
+    expect(getLsps1Tool('lsp_estimate_fees')?.name).toBe('lsp_estimate_fees');
+    expect(getLsps1Tool('nope')).toBeUndefined();
+  });
+});
+
+describe('bindLsps1Tools', () => {
+  const echoHandlers = (): Record<string, Lsps1Handler> => ({
+    lsp_get_info:         async () => ({ ok: true, t: 'get_info' }),
+    lsp_get_network_info: async () => ({ ok: true, t: 'get_network_info' }),
+    lsp_estimate_fees:    async (a) => ({ ok: true, t: 'estimate_fees', args: a }),
+    lsp_create_order:     async (a) => ({ ok: true, t: 'create_order', args: a }),
+    lsp_get_order:        async (a) => ({ ok: true, t: 'get_order', args: a }),
+  });
+
+  it('binds every tool and preserves the spend gate', () => {
+    const src = bindLsps1Tools(echoHandlers());
+    expect(src.listTools().length).toBe(5);
+    const create = src.listTools().find((t) => t.name === 'lsp_create_order');
+    expect(create?.requiresConfirmation).toBe(true);
+    const info = src.listTools().find((t) => t.name === 'lsp_get_info');
+    expect(info?.requiresConfirmation).toBeFalsy();
+  });
+
+  it('dispatches with args', async () => {
+    const src = bindLsps1Tools(echoHandlers());
+    const r = await src.execute('lsp_estimate_fees', { lsp_balance_sat: 500_000 });
+    expect(r).toMatchObject({ ok: true, t: 'estimate_fees', args: { lsp_balance_sat: 500_000 } });
+  });
+
+  it('throws on a missing handler unless allowMissing', () => {
+    const partial = { lsp_get_info: echoHandlers().lsp_get_info };
+    expect(() => bindLsps1Tools(partial)).toThrow(/no handler/);
+    const src = bindLsps1Tools(partial, { allowMissing: true });
+    expect(src.listTools().map((t) => t.name)).toEqual(['lsp_get_info']);
+  });
+
+  it('uses opts.id for the ToolSource id', () => {
+    const src = bindLsps1Tools(echoHandlers(), { id: 'lsp-prod' });
+    expect(src.id).toBe('lsp-prod');
+  });
+});

package/src/lsps1/contract.ts

@@ -0,0 +1,132 @@
+/**
+ * Canonical LSPS1 tool contract — Lightning Service Provider channel orders.
+ *
+ * LSPS1 is a transport-agnostic protocol for buying inbound channel liquidity
+ * from a Lightning Service Provider. The maker happens to implement it, but a
+ * different LSP could too — so the tool names are LSP-agnostic (`lsp_*`),
+ * not `kaleidoswap_*`. The host's binder decides which LSP they reach.
+ *
+ * Every surface implements THESE EXACT tools, only the transport differs:
+ *   - mobile  → in-process handlers over the WDK LSP adapter
+ *   - desktop → HTTP / MCP / CLI handlers
+ *   - eval    → stub handlers
+ *
+ * `lsp_create_order` is a spend → confirmation-gated.
+ *
+ * Pure data — no deps, no fetch, RN-safe.
+ */
+
+import type { ToolDef } from '../types.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { InProcessTool } from '../tools/in-process.js';
+
+export interface Lsps1ToolDef extends ToolDef {
+  /** Moves funds → confirmation-gated. */
+  spend?: boolean;
+}
+
+type Props = Record<string, { type: string; description?: string; enum?: string[] }>;
+
+function t(name: string, description: string, properties: Props = {}, required: string[] = [], spend = false): Lsps1ToolDef {
+  return {
+    name,
+    description,
+    spend,
+    requiresConfirmation: spend,
+    parameters: { type: 'object', properties, required },
+  };
+}
+
+/**
+ * The canonical LSPS1 tool list — agent-facing schemas. Each host's binder
+ * translates these args into the LSP's request body (LSPS1 JSON-RPC, the
+ * KaleidoSwap maker's REST routes, MCP, or a WDK adapter call).
+ */
+export const LSPS1_TOOLS: Lsps1ToolDef[] = [
+  t('lsp_get_info',
+    "Get the LSP's capabilities: minimum/maximum channel size, supported expiries, fee structure, accepted payment options. Use this before estimating or ordering a channel. No args."),
+
+  t('lsp_get_network_info',
+    "Get the LSP's Lightning network info: pubkey, host, port, connect URI. Useful to display the counterparty or pre-connect a peer. No args."),
+
+  t('lsp_estimate_fees',
+    "Estimate the fee for a channel order BEFORE committing. Returns the total cost in sats plus any LSP routing fee. Re-estimate rather than reusing a stale value.",
+    {
+      lsp_balance_sat:    { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
+      client_balance_sat: { type: 'number', description: "Sats the user pre-funds into the channel (push amount). Often 0." },
+      channel_expiry_blocks: { type: 'number', description: 'Optional minimum lease in blocks. Defaults to the LSP minimum.' },
+    },
+    ['lsp_balance_sat']),
+
+  t('lsp_create_order',
+    "Create a channel order. SPEND: confirmation-gated. Returns an order id + a Lightning invoice the user pays to lock the order. The channel opens only after payment.",
+    {
+      lsp_balance_sat:    { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
+      client_balance_sat: { type: 'number', description: 'Sats the user pre-funds. Often 0.' },
+      channel_expiry_blocks: { type: 'number', description: 'Minimum lease in blocks. Defaults to LSP minimum from lsp_get_info.' },
+      refund_onchain_address: { type: 'string', description: 'Optional on-chain refund address if the LSP cannot open the channel.' },
+    },
+    ['lsp_balance_sat'],
+    /* spend */ true),
+
+  t('lsp_get_order',
+    'Check the status of an LSPS1 order — pending / paid / opening / completed / failed. Poll after creating an order until the channel opens.',
+    {
+      order_id: { type: 'string', description: 'The order id from lsp_create_order.' },
+    },
+    ['order_id']),
+];
+
+/** All LSPS1 tool names that move funds (confirmation-gated). */
+export const LSPS1_SPEND_TOOLS: Set<string> = new Set(
+  LSPS1_TOOLS.filter((t) => t.spend).map((t) => t.name),
+);
+
+export function isLsps1SpendTool(name: string): boolean {
+  return LSPS1_SPEND_TOOLS.has(name);
+}
+
+export function getLsps1Tool(name: string): Lsps1ToolDef | undefined {
+  return LSPS1_TOOLS.find((t) => t.name === name);
+}
+
+/** A handler bound to one LSPS1 tool. */
+export type Lsps1Handler = (args: Record<string, unknown>) => Promise<unknown>;
+
+export interface BindLsps1Options {
+  /** Skip tools without a handler instead of throwing (default false). */
+  allowMissing?: boolean;
+  /** ToolSource id for the registry (default 'lsps1'). */
+  id?: string;
+}
+
+/**
+ * Bind LSPS1 contract tools to in-process handlers → an InProcessToolSource.
+ *
+ *   const source = bindLsps1Tools({
+ *     lsp_get_info:        async () => makerLsp.getInfo(),
+ *     lsp_estimate_fees:   async (args) => makerLsp.estimateFees(args),
+ *     lsp_create_order:    async (args) => makerLsp.createOrder(args),
+ *     lsp_get_order:       async ({ order_id }) => makerLsp.getOrder(order_id),
+ *     lsp_get_network_info:async () => makerLsp.networkInfo(),
+ *   });
+ *   tools.register(source);
+ */
+export function bindLsps1Tools(handlers: Record<string, Lsps1Handler>, opts: BindLsps1Options = {}): InProcessToolSource {
+  const bound: InProcessTool[] = [];
+  for (const def of LSPS1_TOOLS) {
+    const handler = handlers[def.name];
+    if (!handler) {
+      if (opts.allowMissing) continue;
+      throw new Error(`bindLsps1Tools: no handler for "${def.name}"`);
+    }
+    bound.push({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+      requiresConfirmation: def.requiresConfirmation,
+      handler,
+    });
+  }
+  return new InProcessToolSource(opts.id ?? 'lsps1', bound);
+}

package/src/memory/memory.test.ts

@@ -0,0 +1,140 @@
+/** Memory store + tool tests — deterministic, no embeddings needed. */
+
+import { describe, it, expect, vi } from 'vitest';
+import { InMemoryMemoryStore } from './store.js';
+import { createMemoryToolSource } from './tool.js';
+import type { MemoryItem, MemoryIO } from './types.js';
+
+describe('InMemoryMemoryStore', () => {
+  it('adds and recalls by recency when no query text', async () => {
+    let t = 1000;
+    const store = new InMemoryMemoryStore({ now: () => t++ });
+    await store.add({ text: 'first', kind: 'note' });
+    await store.add({ text: 'second', kind: 'note' });
+    const all = await store.search({ limit: 5 });
+    expect(all.map((m) => m.text)).toEqual(['second', 'first']); // newest first
+  });
+
+  it('filters by kind + tags, ranks substring hits first', async () => {
+    let t = 0;
+    const store = new InMemoryMemoryStore({ now: () => ++t });
+    await store.add({ text: 'likes cold brew', kind: 'preference', tags: ['coffee'] });
+    await store.add({ text: 'paid rent', kind: 'event' });
+    await store.add({ text: 'prefers dark mode', kind: 'preference', tags: ['ui'] });
+
+    const prefs = await store.search({ kind: 'preference', limit: 5 });
+    expect(prefs).toHaveLength(2);
+
+    const coffee = await store.search({ tags: ['coffee'], limit: 5 });
+    expect(coffee.map((m) => m.text)).toEqual(['likes cold brew']);
+
+    const hit = await store.search({ text: 'dark', limit: 5 });
+    expect(hit[0].text).toBe('prefers dark mode');
+  });
+
+  it('persists through injected IO (load + save)', async () => {
+    const saved: MemoryItem[] = [];
+    const io: MemoryIO = {
+      load: vi.fn(async () => [...saved]),
+      save: vi.fn(async (items) => {
+        saved.length = 0;
+        saved.push(...items);
+      }),
+    };
+    const store = new InMemoryMemoryStore({ io, now: () => 1 });
+    await store.add({ text: 'remember me', kind: 'fact' });
+    expect(io.save).toHaveBeenCalled();
+    expect(saved).toHaveLength(1);
+
+    // A fresh store hydrates from the same IO.
+    const store2 = new InMemoryMemoryStore({ io, now: () => 2 });
+    expect((await store2.all())[0].text).toBe('remember me');
+  });
+
+  it('semantic recall when an embedder is wired', async () => {
+    // 2-dim embeddings: dimension 0 = "wallet"-ness, 1 = "weather"-ness.
+    const embed = async (text: string): Promise<number[]> =>
+      /balance|wallet|sats/i.test(text) ? [1, 0] : [0, 1];
+    const store = new InMemoryMemoryStore({ embed, now: () => 1 });
+    await store.add({ text: 'user wallet balance is low', kind: 'fact' });
+    await store.add({ text: 'it is sunny today', kind: 'note' });
+    const hits = await store.search({ text: 'how many sats do I have', limit: 1 });
+    expect(hits[0].text).toMatch(/wallet balance/);
+  });
+
+  // Embedding-only dedup: same vector → near-dup → newer supersedes older. No LLM.
+  it('consolidate (dedup): near-duplicates supersede instead of appending', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9 },
+      now: () => ++t,
+    });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'user prefers EUR for fiat display', kind: 'preference' });
+
+    const all = await store.all();
+    expect(all).toHaveLength(1); // folded, not appended
+    expect(all[0].text).toBe('user prefers EUR for fiat display'); // newer wins
+  });
+
+  it('consolidate (dedup): distinct facts are kept separate', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'it is sunny today', kind: 'note' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  it('consolidate (dedup): different kinds are never merged', async () => {
+    const embed = async (): Promise<number[]> => [1, 0]; // identical vectors
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'EUR', kind: 'preference' });
+    await store.add({ text: 'EUR', kind: 'fact' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  // LLM merge: injected merger rewrites old + new into one consolidated item, with unioned tags.
+  it('consolidate (merge): injected merger folds near-dups into one item', async () => {
+    const embed = async (): Promise<number[]> => [1, 0];
+    const merge = vi.fn(async (existing: string, incoming: string) => `${existing}; ${incoming}`);
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9, merge },
+      now: () => ++t,
+    });
+    await store.add({ text: 'likes EUR', kind: 'preference', tags: ['fiat'] });
+    await store.add({ text: 'and CHF', kind: 'preference', tags: ['currency'] });
+
+    expect(merge).toHaveBeenCalledWith('likes EUR', 'and CHF');
+    const all = await store.all();
+    expect(all).toHaveLength(1);
+    expect(all[0].text).toBe('likes EUR; and CHF');
+    expect(all[0].tags).toEqual(['fiat', 'currency']); // unioned
+  });
+});
+
+describe('memory tool source', () => {
+  it('remember saves and recall returns matches', async () => {
+    const store = new InMemoryMemoryStore({ now: () => 1 });
+    const src = createMemoryToolSource(store);
+    expect(src.listTools().map((t) => t.name)).toEqual(['remember', 'recall']);
+
+    const saved = await src.execute('remember', { text: 'BTC only', kind: 'preference' });
+    expect(String(saved)).toMatch(/Remembered \(preference\)/);
+
+    const recalled = await src.execute('recall', { query: 'BTC' });
+    expect(String(recalled)).toMatch(/BTC only/);
+  });
+
+  it('defaults an invalid kind to note', async () => {
+    const store = new InMemoryMemoryStore({ now: () => 1 });
+    const src = createMemoryToolSource(store);
+    await src.execute('remember', { text: 'x', kind: 'banana' });
+    expect((await store.all())[0].kind).toBe('note');
+  });
+});

package/src/memory/store.ts

@@ -0,0 +1,174 @@
+/**
+ * MemoryStore implementation — in-memory, with optional injected persistence
+ * and optional semantic ranking. Pure TS, zero deps.
+ *
+ *   const store = new InMemoryMemoryStore();                // ephemeral
+ *   const store = new InMemoryMemoryStore({ io });          // persisted (RN/Node)
+ *   const store = new InMemoryMemoryStore({ io, embed });   // + semantic recall
+ */
+
+import { cosineSimilarity } from '../rag/vector-store.js';
+import type {
+  MemoryConsolidation,
+  MemoryIO,
+  MemoryItem,
+  MemoryQuery,
+  MemoryStore,
+  NewMemory,
+} from './types.js';
+
+const DEFAULT_DEDUP_THRESHOLD = 0.92;
+
+export interface MemoryStoreOptions {
+  /** Persistence (load on first use, save on writes). Omit for ephemeral memory. */
+  io?: MemoryIO;
+  /** Embed text for semantic recall. Omit to fall back to substring matching. */
+  embed?: (text: string) => Promise<number[]>;
+  /**
+   * Fold near-duplicate writes into one item instead of appending. Needs `embed`.
+   * Omit for append-only. See {@link MemoryConsolidation}.
+   */
+  consolidate?: MemoryConsolidation;
+  /** Clock — injectable for deterministic tests. */
+  now?: () => number;
+}
+
+export class InMemoryMemoryStore implements MemoryStore {
+  private items: MemoryItem[] = [];
+  private hydrated = false;
+  private counter = 0;
+  private readonly io?: MemoryIO;
+  private readonly embed?: (text: string) => Promise<number[]>;
+  private readonly consolidate?: MemoryConsolidation;
+  private readonly now: () => number;
+
+  constructor(opts: MemoryStoreOptions = {}) {
+    this.io = opts.io;
+    this.embed = opts.embed;
+    this.consolidate = opts.consolidate;
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  private async hydrate(): Promise<void> {
+    if (this.hydrated) return;
+    this.hydrated = true;
+    if (this.io) {
+      try {
+        this.items = await this.io.load();
+        this.counter = this.items.length;
+      } catch {
+        this.items = [];
+      }
+    }
+  }
+
+  private async persist(): Promise<void> {
+    if (this.io) await this.io.save(this.items);
+  }
+
+  async add(item: NewMemory): Promise<MemoryItem> {
+    await this.hydrate();
+    let text = item.text;
+    let embedding =
+      item.embedding ?? (this.embed ? await this.embed(text).catch(() => undefined) : undefined);
+    let tags = item.tags;
+    let supersedeId: string | undefined;
+
+    // Consolidation: fold a same-kind near-duplicate into this write instead of
+    // appending — embedding-only by default, LLM rewrite when `merge` is set.
+    if (this.consolidate && embedding) {
+      const threshold = this.consolidate.threshold ?? DEFAULT_DEDUP_THRESHOLD;
+      let best: { item: MemoryItem; score: number } | undefined;
+      for (const m of this.items) {
+        if (m.kind !== item.kind || !m.embedding) continue;
+        const score = cosineSimilarity(embedding, m.embedding);
+        if (!best || score > best.score) best = { item: m, score };
+      }
+      if (best && best.score >= threshold) {
+        supersedeId = best.item.id;
+        tags = unionTags(best.item.tags, item.tags);
+        if (this.consolidate.merge) {
+          const merged = await this.consolidate.merge(best.item.text, text).catch(() => null);
+          if (merged && merged.trim()) {
+            text = merged.trim();
+            if (this.embed) embedding = await this.embed(text).catch(() => embedding);
+          }
+        }
+        // No merger → the incoming (newer) text supersedes the older item as-is.
+      }
+    }
+
+    const full: MemoryItem = {
+      id: item.id ?? `mem_${this.now()}_${++this.counter}`,
+      text,
+      kind: item.kind,
+      tags,
+      createdAt: item.createdAt ?? this.now(),
+      ...(embedding ? { embedding } : {}),
+    };
+    if (supersedeId) this.items = this.items.filter((m) => m.id !== supersedeId);
+    this.items.push(full);
+    await this.persist();
+    return full;
+  }
+
+  async all(): Promise<MemoryItem[]> {
+    await this.hydrate();
+    return [...this.items];
+  }
+
+  async search(query: MemoryQuery): Promise<MemoryItem[]> {
+    await this.hydrate();
+    const limit = query.limit ?? 5;
+
+    let pool = this.items;
+    if (query.kind) pool = pool.filter((m) => m.kind === query.kind);
+    if (query.tags?.length) {
+      pool = pool.filter((m) => query.tags!.every((t) => m.tags?.includes(t)));
+    }
+
+    const text = query.text?.trim();
+    if (!text) {
+      // No query text → most recent first.
+      return [...pool].sort((a, b) => b.createdAt - a.createdAt).slice(0, limit);
+    }
+
+    // Semantic ranking when both the query and items are embedded.
+    if (this.embed && pool.some((m) => m.embedding)) {
+      const qv = await this.embed(text).catch(() => null);
+      if (qv) {
+        return [...pool]
+          .map((m) => ({ m, score: m.embedding ? cosineSimilarity(qv, m.embedding) : -1 }))
+          .sort((a, b) => b.score - a.score)
+          .slice(0, limit)
+          .map((x) => x.m);
+      }
+    }
+
+    // Fallback: substring score + recency.
+    const q = text.toLowerCase();
+    return [...pool]
+      .map((m) => ({ m, hit: m.text.toLowerCase().includes(q) ? 1 : 0 }))
+      .sort((a, b) => b.hit - a.hit || b.m.createdAt - a.m.createdAt)
+      .slice(0, limit)
+      .map((x) => x.m);
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.hydrate();
+    this.items = this.items.filter((m) => m.id !== id);
+    await this.persist();
+  }
+
+  async clear(): Promise<void> {
+    await this.hydrate();
+    this.items = [];
+    await this.persist();
+  }
+}
+
+/** Merge two optional tag lists, de-duplicated. Returns undefined when both empty. */
+function unionTags(a?: string[], b?: string[]): string[] | undefined {
+  if (!a?.length && !b?.length) return undefined;
+  return [...new Set([...(a ?? []), ...(b ?? [])])];
+}

package/src/memory/tool.ts

@@ -0,0 +1,76 @@
+/**
+ * Memory tool source — lets the agent persist and recall things across
+ * sessions (`remember`, `recall`). Pairs with auto-recall in the
+ * ContextBuilder; this is the explicit, agent-driven side.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from '../tools/source.js';
+import type { MemoryKind, MemoryStore } from './types.js';
+
+const REMEMBER = 'remember';
+const RECALL = 'recall';
+const KINDS: MemoryKind[] = ['fact', 'preference', 'event', 'note'];
+
+export function createMemoryToolSource(store: MemoryStore): ToolSource {
+  const tools: ToolDef[] = [
+    {
+      name: REMEMBER,
+      description:
+        'Save something to long-term memory so you recall it in future sessions ' +
+        '— a user preference, a fact, or an event. Use sparingly for durable info.',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'What to remember (a short sentence)' },
+          kind: { type: 'string', enum: KINDS, description: 'fact | preference | event | note' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags' },
+        },
+        required: ['text'],
+      },
+    },
+    {
+      name: RECALL,
+      description:
+        'Search your long-term memory for what you know about something before answering.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'What to recall' },
+          limit: { type: 'number', description: 'Max items (default 5)' },
+        },
+        required: ['query'],
+      },
+    },
+  ];
+
+  async function execute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    if (name === REMEMBER) {
+      const text = String(args.text ?? '').trim();
+      if (!text) throw new Error('remember: text is required');
+      const kind = (KINDS as string[]).includes(String(args.kind))
+        ? (args.kind as MemoryKind)
+        : 'note';
+      const tags = Array.isArray(args.tags) ? args.tags.map(String) : undefined;
+      const item = await store.add({ text, kind, tags });
+      return `Remembered (${item.kind}): ${item.text}`;
+    }
+    if (name === RECALL) {
+      const query = String(args.query ?? '').trim();
+      if (!query) throw new Error('recall: query is required');
+      const limit = Number(args.limit) > 0 ? Number(args.limit) : 5;
+      const items = await store.search({ text: query, limit });
+      if (items.length === 0) return 'Nothing relevant in memory.';
+      return items.map((m) => `- (${m.kind}) ${m.text}`).join('\n');
+    }
+    throw new Error(`memory: unknown tool ${name}`);
+  }
+
+  const names = new Set([REMEMBER, RECALL]);
+  return {
+    id: 'memory',
+    listTools: () => tools,
+    has: (name) => names.has(name),
+    execute,
+  };
+}

package/src/memory/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Memory — the agent's persistent identity + what it has learned.
+ *
+ * Two layers, mirroring how nanobot splits SOUL.md / AGENTS.md / memory:
+ *   - AgentProfile  — static identity ("who am I, how do I behave"). Injected.
+ *   - MemoryStore   — durable, growing facts/preferences/events the agent
+ *                     remembers across sessions. Pluggable storage.
+ *
+ * Pure data + interfaces — no storage or embedding deps. The host injects
+ * persistence (AsyncStorage on RN, fs/SQLite on Node) and, optionally, an
+ * EmbeddingProvider for semantic recall.
+ */
+
+/** Static agent identity, composed into the system prompt every turn. */
+export interface AgentProfile {
+  /** Display name, e.g. "KaleidoMind". */
+  name: string;
+  /** Persona / identity — the "soul". Who the agent is, its voice, its values. */
+  soul: string;
+  /** Operating instructions / house rules (optional). */
+  instructions?: string;
+}
+
+export type MemoryKind = 'fact' | 'preference' | 'event' | 'note';
+
+export interface MemoryItem {
+  id: string;
+  text: string;
+  kind: MemoryKind;
+  /** Epoch ms. */
+  createdAt: number;
+  tags?: string[];
+  /** Optional embedding for semantic recall (set when an embedder is wired). */
+  embedding?: number[];
+}
+
+/** What to add — id/createdAt/embedding are filled in by the store. */
+export type NewMemory = Omit<MemoryItem, 'id' | 'createdAt' | 'embedding'> &
+  Partial<Pick<MemoryItem, 'id' | 'createdAt' | 'embedding'>>;
+
+export interface MemoryQuery {
+  /** Free text to match (semantic if embeddings are available, else substring). */
+  text?: string;
+  kind?: MemoryKind;
+  tags?: string[];
+  /** Max items to return (default 5). */
+  limit?: number;
+}
+
+export interface MemoryStore {
+  add(item: NewMemory): Promise<MemoryItem>;
+  all(): Promise<MemoryItem[]>;
+  /** Best-matching items for the query (recency-ranked, or semantic if embedded). */
+  search(query: MemoryQuery): Promise<MemoryItem[]>;
+  remove(id: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/** Injected persistence — load once, save on every mutation. RN/Node provide it. */
+export interface MemoryIO {
+  load(): Promise<MemoryItem[]>;
+  save(items: MemoryItem[]): Promise<void>;
+}
+
+/**
+ * Consolidation — fold same-kind near-duplicate memories into one item instead
+ * of bloating with "user likes EUR" ×5. Needs embeddings (the dup check is
+ * cosine). Omit for append-only. Two tiers: embedding-only dedup (zero
+ * inference, mobile-safe) and, when `merge` is set, an LLM rewrite.
+ */
+export interface MemoryConsolidation {
+  /** Cosine threshold above which two same-kind memories are "the same". Default 0.92. */
+  threshold?: number;
+  /** Optional LLM merger; without it the newer item simply supersedes the older. */
+  merge?: (existing: string, incoming: string) => Promise<string>;
+}