@kaleidorg/mind 0.0.1 → 0.2.0

package/src/knowledge/bitcoin-copilot.ts

@@ -0,0 +1,177 @@
+/**
+ * Bitcoin-copilot knowledge pack — a curated, on-brand corpus to RAG over so an
+ * on-device assistant can answer Bitcoin / Lightning / RGB / KaleidoSwap
+ * questions privately. Ship it, ingest it with a Retriever, done.
+ *
+ * Concise + accurate. Extend or replace with your own docs (BOLT specs, RGB
+ * docs, app help, FAQs) — the format is just `RagDocument[]`.
+ */
+
+import type { RagDocument } from '../rag/types.js';
+
+export const BITCOIN_COPILOT_DOCS: RagDocument[] = [
+  {
+    id: 'inbound-liquidity',
+    text:
+      'To RECEIVE Lightning payments you need inbound liquidity — remote balance ' +
+      'on a channel pointing at you. Brand-new wallets have none, so they can ' +
+      'send but not receive. Get inbound liquidity by buying a channel from an ' +
+      'LSP, or by receiving an on-chain deposit and swapping it into a channel.',
+    metadata: { topic: 'liquidity' },
+  },
+  {
+    id: 'outbound-liquidity',
+    text:
+      'Outbound liquidity is your local balance on a channel — what you can ' +
+      'spend over Lightning. You get it by funding a channel yourself or being ' +
+      'pushed funds. If you can receive but not send, you lack outbound liquidity.',
+    metadata: { topic: 'liquidity' },
+  },
+  {
+    id: 'channel-basics',
+    text:
+      'A Lightning channel is a 2-of-2 multisig funding output shared by two ' +
+      'peers. It lets them send instant, low-fee payments off-chain by updating ' +
+      'who owns how much, without touching the blockchain until the channel closes.',
+    metadata: { topic: 'lightning' },
+  },
+  {
+    id: 'onchain-vs-lightning',
+    text:
+      'On-chain Bitcoin transactions settle directly on the blockchain: final, ' +
+      'but slower and with miner fees. Lightning payments are instant and cheap ' +
+      'but require channels with liquidity. Use Lightning for spending, on-chain ' +
+      'for settlement and for funding channels.',
+    metadata: { topic: 'lightning' },
+  },
+  {
+    id: 'open-channel',
+    text:
+      'Opening a channel funds a 2-of-2 output on-chain; it confirms in one or ' +
+      'more blocks (or is usable immediately with 0-conf if the peer allows). ' +
+      'The funder gets outbound liquidity. To get inbound, buy a channel from an ' +
+      'LSP instead of opening your own.',
+    metadata: { topic: 'channels' },
+  },
+  {
+    id: 'lsp-lsps1',
+    text:
+      'An LSP (Lightning Service Provider) sells channels. With LSPS1 you place ' +
+      'a channel order: choose capacity and how much inbound liquidity you want, ' +
+      'pay the fee, and the LSP opens a channel to you — often 0-conf, so you can ' +
+      'receive right away. KaleidoSwap acts as an LSP.',
+    metadata: { topic: 'channels' },
+  },
+  {
+    id: 'atomic-swap',
+    text:
+      'An atomic (HTLC) swap exchanges two assets so that either both legs ' +
+      'happen or neither does — no counterparty can run off with your funds. ' +
+      'KaleidoSwap uses a 5-step HTLC taker flow for trustless swaps.',
+    metadata: { topic: 'swaps' },
+  },
+  {
+    id: 'submarine-swap',
+    text:
+      'A submarine swap moves value between on-chain Bitcoin and Lightning ' +
+      'atomically via an HTLC: send on-chain BTC and receive it on Lightning, or ' +
+      'vice-versa, with no custodian. Useful to refill inbound/outbound liquidity.',
+    metadata: { topic: 'swaps' },
+  },
+  {
+    id: 'rgb-assets',
+    text:
+      'RGB is a protocol for issuing assets — like USDT and XAUT — on top of ' +
+      'Bitcoin and Lightning. Validation is client-side, which keeps it private ' +
+      'and scalable. On KaleidoSwap you can hold and swap RGB assets.',
+    metadata: { topic: 'rgb' },
+  },
+  {
+    id: 'colored-channels',
+    text:
+      'A colored channel is a Lightning channel that also carries an RGB asset ' +
+      'balance, so you can send/receive USDT or XAUT over Lightning instantly. ' +
+      'Buying an asset channel from the LSP gives you inbound capacity for that asset.',
+    metadata: { topic: 'rgb' },
+  },
+  {
+    id: 'rgb-invoice',
+    text:
+      'An RGB invoice requests a specific asset and amount and includes a ' +
+      'blinded UTXO so the sender can transfer the asset privately. It differs ' +
+      'from a plain Lightning (BOLT11) invoice, which is for BTC.',
+    metadata: { topic: 'rgb' },
+  },
+  {
+    id: 'rfq-quote',
+    text:
+      'Before a swap, KaleidoSwap gives a quote via RFQ (request for quote): the ' +
+      'maker prices the pair (e.g. BTC/USDT) and returns the amount you will ' +
+      'receive and the fees. Quotes expire — re-quote if you wait.',
+    metadata: { topic: 'trading' },
+  },
+  {
+    id: 'maker-taker',
+    text:
+      'KaleidoSwap is maker-based: a maker provides liquidity and prices, you ' +
+      'are the taker who accepts a quote and executes the atomic swap. The maker ' +
+      'also runs the LSP that sells channels.',
+    metadata: { topic: 'trading' },
+  },
+  {
+    id: 'mpp',
+    text:
+      'Multi-path payments (MPP) split one Lightning payment across several ' +
+      'channels/routes so you can send more than any single channel allows. The ' +
+      'parts recombine at the destination atomically.',
+    metadata: { topic: 'lightning' },
+  },
+  {
+    id: 'lightning-fees',
+    text:
+      'Lightning fees are tiny: a base fee plus a proportional fee per hop, paid ' +
+      'to routing nodes. They are far smaller than on-chain miner fees, which is ' +
+      'why Lightning suits everyday spending.',
+    metadata: { topic: 'fees' },
+  },
+  {
+    id: 'zero-conf',
+    text:
+      '0-conf (zero-confirmation) means a channel is usable before its funding ' +
+      'transaction is mined. It relies on trusting the channel partner not to ' +
+      'double-spend; LSPs commonly offer it so you can receive instantly.',
+    metadata: { topic: 'channels' },
+  },
+  {
+    id: 'seed-backup',
+    text:
+      'Your seed phrase (12/24 words) controls your funds. Write it down offline ' +
+      'and never share or photograph it. A KaleidoSwap node also needs channel ' +
+      'state backups: losing them can mean losing funds in open channels.',
+    metadata: { topic: 'security' },
+  },
+  {
+    id: 'receiving',
+    text:
+      'To receive: share a Lightning invoice (BOLT11) or an on-chain address. ' +
+      'For Lightning you need inbound liquidity first. For RGB assets, share an ' +
+      'RGB invoice. On-chain always works but is slower.',
+    metadata: { topic: 'usage' },
+  },
+  {
+    id: 'sending',
+    text:
+      'To send: pay a Lightning invoice or a Lightning address for BTC, or use ' +
+      'an on-chain address. You need outbound liquidity for Lightning. Always ' +
+      'check the amount and destination before paying.',
+    metadata: { topic: 'usage' },
+  },
+  {
+    id: 'dca',
+    text:
+      'Dollar-cost averaging (DCA) buys a fixed amount on a schedule to smooth ' +
+      'out price swings. KaleidoSwap can automate recurring swaps so you ' +
+      'accumulate BTC or an asset over time without timing the market.',
+    metadata: { topic: 'trading' },
+  },
+];

package/src/knowledge/knowledge.test.ts

@@ -0,0 +1,63 @@
+/** Knowledge pack + corpus adapter tests — pure transforms. */
+
+import { describe, it, expect } from 'vitest';
+import { BITCOIN_COPILOT_DOCS } from './bitcoin-copilot.js';
+import { walletHistoryToDocuments, contactsToDocuments } from './wallet.js';
+import { merchantsToDocuments } from './merchants.js';
+
+describe('BITCOIN_COPILOT_DOCS', () => {
+  it('is a non-trivial corpus with unique ids and real text', () => {
+    expect(BITCOIN_COPILOT_DOCS.length).toBeGreaterThanOrEqual(15);
+    const ids = BITCOIN_COPILOT_DOCS.map((d) => d.id);
+    expect(new Set(ids).size).toBe(ids.length); // unique
+    expect(BITCOIN_COPILOT_DOCS.every((d) => (d.text?.length ?? 0) > 40)).toBe(true);
+    // covers the key concept the hero demo asks about
+    expect(BITCOIN_COPILOT_DOCS.some((d) => /inbound liquidity/i.test(d.text))).toBe(true);
+  });
+});
+
+describe('walletHistoryToDocuments', () => {
+  it('renders sent/received sentences with date, amount, counterparty', () => {
+    const docs = walletHistoryToDocuments([
+      { id: 't1', type: 'send', amountSats: 5000, counterparty: 'Bob', memo: 'lunch', timestamp: 1700000000000 },
+      { id: 't2', type: 'receive', amountSats: 21000, counterparty: 'Alice', timestamp: 1700100000000 },
+      { type: 'swap', amountSats: 100000, asset: 'USDT' },
+    ]);
+    expect(docs[0].text).toMatch(/you sent 5000 sats to Bob — "lunch"/);
+    expect(docs[1].text).toMatch(/you received 21000 sats from Alice/);
+    expect(docs[2].text).toMatch(/you swapped 100000 USDT/);
+    expect(docs[2].id).toBe('tx_2'); // id defaulted
+    expect(docs[0].metadata?.kind).toBe('transaction');
+  });
+});
+
+describe('contactsToDocuments', () => {
+  it('includes address/nostr/note and skips empty contacts', () => {
+    const docs = contactsToDocuments([
+      { name: 'Bob', lightningAddress: 'bob@getalby.com', note: 'coffee buddy' },
+      {}, // skipped
+    ]);
+    expect(docs).toHaveLength(1);
+    expect(docs[0].text).toMatch(/Contact: Bob — Lightning address bob@getalby.com, coffee buddy/);
+  });
+});
+
+describe('merchantsToDocuments', () => {
+  it('renders place + acceptance and preserves coordinates in metadata', () => {
+    const docs = merchantsToDocuments([
+      {
+        name: 'Bitcoin Café',
+        category: 'cafe',
+        address: 'Via Nassa 1',
+        city: 'Lugano',
+        lat: 46.0,
+        lng: 8.95,
+        acceptedAssets: ['lightning', 'onchain'],
+      },
+      { city: 'nowhere' }, // no name → skipped
+    ]);
+    expect(docs).toHaveLength(1);
+    expect(docs[0].text).toMatch(/Bitcoin Café \(cafe\) at Via Nassa 1, Lugano\. Accepts lightning, onchain\./);
+    expect(docs[0].metadata).toMatchObject({ kind: 'merchant', lat: 46.0, lng: 8.95, city: 'Lugano' });
+  });
+});

package/src/knowledge/merchants.ts

@@ -0,0 +1,49 @@
+/**
+ * BTC map discovery — turn a merchant directory (e.g. BTCMap / a local dataset)
+ * into `RagDocument[]` so the agent can answer "where can I spend Bitcoin for
+ * coffee near me?" with on-device semantic search over places.
+ *
+ * Pure transform over a generic Merchant shape. Coordinates are kept in
+ * metadata so the host can still pin results on a map after retrieval.
+ */
+
+import type { RagDocument } from '../rag/types.js';
+
+export interface Merchant {
+  id?: string;
+  name?: string;
+  category?: string; // 'cafe' | 'restaurant' | 'shop' | …
+  address?: string;
+  city?: string;
+  lat?: number;
+  lng?: number;
+  /** e.g. ['onchain', 'lightning', 'rgb']. */
+  acceptedAssets?: string[];
+  description?: string;
+}
+
+/** One searchable doc per merchant; lat/lng preserved in metadata for mapping. */
+export function merchantsToDocuments(merchants: Merchant[]): RagDocument[] {
+  return merchants
+    .filter((m) => m.name)
+    .map((m, i) => {
+      const where = [m.address, m.city].filter(Boolean).join(', ');
+      const pays = m.acceptedAssets?.length
+        ? `Accepts ${m.acceptedAssets.join(', ')}.`
+        : 'Accepts Bitcoin.';
+      const cat = m.category ? ` (${m.category})` : '';
+      const desc = m.description ? ` ${m.description}` : '';
+      return {
+        id: m.id ?? `merchant_${m.name ?? i}`,
+        text: `${m.name}${cat}${where ? ` at ${where}` : ''}. ${pays}${desc}`.trim(),
+        metadata: {
+          kind: 'merchant',
+          name: m.name,
+          category: m.category,
+          city: m.city,
+          lat: m.lat,
+          lng: m.lng,
+        },
+      };
+    });
+}

package/src/knowledge/wallet.ts

@@ -0,0 +1,84 @@
+/**
+ * Personal wallet knowledge — turn a user's transaction history + contacts into
+ * `RagDocument[]` so the agent can answer "what did I spend on coffee last
+ * month?", "who did I pay 50k sats to?", "summarise my swaps" — all on-device,
+ * nothing leaving the phone.
+ *
+ * Pure transforms over minimal, generic shapes (hosts map their own types in).
+ * No deps, no PII leaves: the host decides what to ingest.
+ */
+
+import type { RagDocument } from '../rag/types.js';
+
+export interface WalletTx {
+  id?: string;
+  /** 'send' | 'receive' | 'swap' | 'deposit' | 'withdraw' | … */
+  type?: string;
+  amountSats?: number;
+  asset?: string; // 'BTC' | 'USDT' | 'XAUT' | …
+  /** Who/where — a name, contact, address, or merchant. */
+  counterparty?: string;
+  memo?: string;
+  status?: string;
+  /** Epoch ms. */
+  timestamp?: number;
+}
+
+export interface Contact {
+  name?: string;
+  lightningAddress?: string;
+  npub?: string;
+  note?: string;
+}
+
+function isoDate(ts?: number): string {
+  if (!ts) return 'an unknown date';
+  // Avoid Date formatting differences — just YYYY-MM-DD from the ISO string.
+  try {
+    return new Date(ts).toISOString().slice(0, 10);
+  } catch {
+    return 'an unknown date';
+  }
+}
+
+/** One short, searchable sentence per transaction. */
+export function walletHistoryToDocuments(txs: WalletTx[]): RagDocument[] {
+  return txs.map((tx, i) => {
+    const date = isoDate(tx.timestamp);
+    const asset = tx.asset ?? 'sats';
+    const amount = tx.amountSats != null ? `${tx.amountSats} ${asset === 'BTC' ? 'sats' : asset}` : 'an amount';
+    const verb =
+      tx.type === 'receive' || tx.type === 'deposit'
+        ? 'received'
+        : tx.type === 'swap'
+          ? 'swapped'
+          : tx.type === 'withdraw'
+            ? 'withdrew'
+            : 'sent';
+    const who = tx.counterparty ? ` ${verb === 'received' ? 'from' : 'to'} ${tx.counterparty}` : '';
+    const memo = tx.memo ? ` — "${tx.memo}"` : '';
+    const status = tx.status && tx.status !== 'complete' ? ` (${tx.status})` : '';
+    return {
+      id: tx.id ?? `tx_${i}`,
+      text: `On ${date} you ${verb} ${amount}${who}${memo}${status}.`,
+      metadata: { kind: 'transaction', type: tx.type, asset: tx.asset, timestamp: tx.timestamp },
+    };
+  });
+}
+
+/** One doc per contact, so "who is Bob?" / "pay my friend" can resolve. */
+export function contactsToDocuments(contacts: Contact[]): RagDocument[] {
+  return contacts
+    .filter((c) => c.name || c.lightningAddress || c.npub)
+    .map((c, i) => {
+      const parts: string[] = [];
+      if (c.lightningAddress) parts.push(`Lightning address ${c.lightningAddress}`);
+      if (c.npub) parts.push(`Nostr ${c.npub}`);
+      if (c.note) parts.push(c.note);
+      return {
+        id: `contact_${c.name ?? c.lightningAddress ?? i}`,
+        text: `Contact: ${c.name ?? 'unnamed'}${parts.length ? ` — ${parts.join(', ')}` : ''}.`,
+        metadata: { kind: 'contact', name: c.name },
+      };
+    });
+}

package/src/memory/memory.test.ts

@@ -0,0 +1,85 @@
+/** 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/);
+  });
+});
+
+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,129 @@
+/**
+ * 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 {
+  MemoryIO,
+  MemoryItem,
+  MemoryQuery,
+  MemoryStore,
+  NewMemory,
+} from './types.js';
+
+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[]>;
+  /** 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 now: () => number;
+
+  constructor(opts: MemoryStoreOptions = {}) {
+    this.io = opts.io;
+    this.embed = opts.embed;
+    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();
+    const embedding =
+      item.embedding ?? (this.embed ? await this.embed(item.text).catch(() => undefined) : undefined);
+    const full: MemoryItem = {
+      id: item.id ?? `mem_${this.now()}_${++this.counter}`,
+      text: item.text,
+      kind: item.kind,
+      tags: item.tags,
+      createdAt: item.createdAt ?? this.now(),
+      ...(embedding ? { embedding } : {}),
+    };
+    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();
+  }
+}

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,
+  };
+}