gsd-pi 2.75.0-dev.2203010a0 → 2.75.0-dev.96d4bb599

package/src/resources/extensions/gsd/tests/memory-embeddings.test.ts

@@ -0,0 +1,213 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { _getAdapter, closeDatabase, openDatabase } from '../gsd-db.ts';
+import { createMemory, queryMemoriesRanked, supersedeMemory } from '../memory-store.ts';
+import {
+  cosineSimilarity,
+  embedMemories,
+  getEmbeddingForMemory,
+  loadAllEmbeddings,
+  packFloat32,
+  removeEmbedding,
+  saveEmbedding,
+  unpackFloat32,
+} from '../memory-embeddings.ts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Float32 packing + cosine math
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-embeddings: packFloat32 / unpackFloat32 round-trip', () => {
+  const vec = new Float32Array([0.1, -0.5, 0.25, 0.75]);
+  const packed = packFloat32(vec);
+  const restored = unpackFloat32(packed);
+  assert.ok(restored);
+  assert.equal(restored!.length, vec.length);
+  for (let i = 0; i < vec.length; i++) {
+    assert.ok(Math.abs(restored![i] - vec[i]) < 1e-6);
+  }
+});
+
+test('memory-embeddings: cosineSimilarity identities', () => {
+  const a = new Float32Array([1, 0, 0]);
+  const b = new Float32Array([1, 0, 0]);
+  const c = new Float32Array([0, 1, 0]);
+  assert.ok(Math.abs(cosineSimilarity(a, b) - 1) < 1e-6);
+  assert.ok(Math.abs(cosineSimilarity(a, c)) < 1e-6);
+  assert.equal(cosineSimilarity(new Float32Array([]), new Float32Array([])), 0);
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// memory_embeddings table round-trip
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-embeddings: saveEmbedding then getEmbeddingForMemory', () => {
+  openDatabase(':memory:');
+  const id = createMemory({ category: 'pattern', content: 'embedding persistence test' });
+  assert.ok(id);
+
+  const vec = new Float32Array([0.1, 0.2, 0.3]);
+  assert.ok(saveEmbedding(id!, vec, 'test-model'));
+
+  const row = getEmbeddingForMemory(id!);
+  assert.ok(row);
+  assert.equal(row!.model, 'test-model');
+  assert.equal(row!.dim, 3);
+  assert.equal(row!.vector.length, 3);
+
+  assert.ok(removeEmbedding(id!));
+  assert.equal(getEmbeddingForMemory(id!), null);
+
+  closeDatabase();
+});
+
+test('memory-embeddings: loadAllEmbeddings skips superseded memories', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'mem A' });
+  createMemory({ category: 'pattern', content: 'mem B' });
+  saveEmbedding('MEM001', new Float32Array([1, 0, 0]), 'm');
+  saveEmbedding('MEM002', new Float32Array([0, 1, 0]), 'm');
+
+  const all = loadAllEmbeddings();
+  assert.equal(all.length, 2);
+
+  // supersede MEM001
+  supersedeMemory('MEM001', 'MEM002');
+
+  const remaining = loadAllEmbeddings();
+  assert.equal(remaining.length, 1);
+  assert.equal(remaining[0].memoryId, 'MEM002');
+
+  closeDatabase();
+});
+
+test('memory-embeddings: embedMemories returns 0 when embedFn is null', async () => {
+  const n = await embedMemories([{ id: 'MEM001', content: 'x' }], null, 'none');
+  assert.equal(n, 0);
+});
+
+test('memory-embeddings: embedMemories persists fetched vectors', async () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'first' });
+  createMemory({ category: 'pattern', content: 'second' });
+
+  const fn = async (texts: string[]): Promise<Float32Array[]> =>
+    texts.map((_, i) => new Float32Array([i, i + 1, i + 2]));
+
+  const count = await embedMemories(
+    [
+      { id: 'MEM001', content: 'first' },
+      { id: 'MEM002', content: 'second' },
+    ],
+    fn,
+    'mock-embedder',
+  );
+  assert.equal(count, 2);
+
+  const first = getEmbeddingForMemory('MEM001');
+  assert.ok(first);
+  assert.equal(first!.model, 'mock-embedder');
+  assert.equal(first!.vector.length, 3);
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// queryMemoriesRanked + FTS5 keyword path
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-store: queryMemoriesRanked returns keyword hits', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'gotcha', content: 'sql.js FTS5 virtual tables need triggers' });
+  createMemory({ category: 'pattern', content: 'prefer prepared statements for hot paths' });
+  createMemory({ category: 'convention', content: 'atomic writes use tmp + rename' });
+
+  const ranked = queryMemoriesRanked({ query: 'sql triggers', k: 5 });
+  assert.ok(ranked.length >= 1);
+  assert.equal(ranked[0].memory.id, 'MEM001');
+  assert.ok(ranked[0].keywordRank !== null);
+  assert.equal(ranked[0].reason, 'keyword');
+
+  closeDatabase();
+});
+
+test('memory-store: queryMemoriesRanked respects scope + tag filters', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'gotcha', content: 'scoped fact one', scope: 'project', tags: ['a'] });
+  createMemory({ category: 'gotcha', content: 'scoped fact two', scope: 'global', tags: ['a', 'b'] });
+
+  const projectOnly = queryMemoriesRanked({ query: 'scoped fact', scope: 'project' });
+  assert.equal(projectOnly.length, 1);
+  assert.equal(projectOnly[0].memory.scope, 'project');
+
+  const tagged = queryMemoriesRanked({ query: 'scoped fact', tag: 'b' });
+  assert.equal(tagged.length, 1);
+  assert.equal(tagged[0].memory.id, 'MEM002');
+
+  closeDatabase();
+});
+
+test('memory-store: queryMemoriesRanked fuses keyword + semantic hits', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'foo bar baz' });
+  createMemory({ category: 'pattern', content: 'completely unrelated' });
+
+  // Embed memory 2 so semantic scoring picks it up even though the keyword
+  // "foo" does not appear in its content.
+  saveEmbedding('MEM001', new Float32Array([1, 0, 0, 0]), 'mock');
+  saveEmbedding('MEM002', new Float32Array([0.9, 0.1, 0, 0]), 'mock');
+
+  const queryVec = new Float32Array([0.95, 0.05, 0, 0]);
+  const ranked = queryMemoriesRanked({ query: 'foo', queryVector: queryVec, k: 5 });
+  const reasons = ranked.map((r) => r.reason);
+  assert.ok(reasons.includes('both') || reasons.includes('keyword'));
+  const ids = ranked.map((r) => r.memory.id);
+  assert.ok(ids.includes('MEM002'), 'semantic-only hit should surface even without keyword match');
+
+  closeDatabase();
+});
+
+test('memory-store: queryMemoriesRanked falls back to ranked listing when query is empty', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'gotcha', content: 'first', confidence: 0.9 });
+  createMemory({ category: 'pattern', content: 'second', confidence: 0.5 });
+
+  const ranked = queryMemoriesRanked({ query: '   ' });
+  assert.equal(ranked.length, 2);
+  assert.equal(ranked[0].memory.id, 'MEM001');
+  assert.equal(ranked[0].reason, 'ranked');
+
+  closeDatabase();
+});
+
+test('memory-store: queryMemoriesRanked excludes superseded by default', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'gotcha', content: 'stale insight' });
+  createMemory({ category: 'gotcha', content: 'fresh insight' });
+
+  supersedeMemory('MEM001', 'MEM002');
+
+  const active = queryMemoriesRanked({ query: 'insight' });
+  assert.ok(active.every((r) => r.memory.superseded_by == null));
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FTS5 triggers keep memories_fts in sync with memories
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-store schema: memories_fts stays in sync with memories', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'alpha beta gamma' });
+  const adapter = _getAdapter();
+  assert.ok(adapter);
+  const fts = adapter!.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+  if (!fts) {
+    // Build without FTS5 — skip.
+    closeDatabase();
+    return;
+  }
+  const rows = adapter!.prepare(`SELECT content FROM memories_fts WHERE memories_fts MATCH 'beta'`).all();
+  assert.ok(rows.some((row) => (row['content'] as string).includes('alpha beta gamma')));
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/memory-ingest.test.ts

@@ -0,0 +1,153 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _getAdapter, closeDatabase, openDatabase } from '../gsd-db.ts';
+import {
+  createMemorySource,
+  deleteMemorySource,
+  getMemorySource,
+  hashContent,
+  listMemorySources,
+} from '../memory-source-store.ts';
+import { ingestFile, ingestNote, summarizeIngest } from '../memory-ingest.ts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// memory-source-store
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-sources: content_hash is stable', () => {
+  const a = hashContent('hello');
+  const b = hashContent('hello');
+  assert.equal(a, b);
+  assert.notEqual(a, hashContent('world'));
+});
+
+test('memory-sources: createMemorySource is idempotent on content_hash', () => {
+  openDatabase(':memory:');
+
+  const first = createMemorySource({
+    kind: 'note',
+    content: 'sql.js FTS5 triggers must be kept in sync with the base table',
+    tags: ['db', 'fts'],
+  });
+  assert.ok(first);
+  assert.equal(first!.duplicate, false);
+
+  const second = createMemorySource({
+    kind: 'note',
+    content: 'sql.js FTS5 triggers must be kept in sync with the base table',
+    tags: ['db', 'fts'],
+  });
+  assert.ok(second);
+  assert.equal(second!.duplicate, true);
+  assert.equal(second!.id, first!.id);
+
+  const sources = listMemorySources();
+  assert.equal(sources.length, 1);
+  assert.equal(sources[0].kind, 'note');
+  assert.deepEqual(sources[0].tags, ['db', 'fts']);
+
+  closeDatabase();
+});
+
+test('memory-sources: getMemorySource and deleteMemorySource round-trip', () => {
+  openDatabase(':memory:');
+
+  const created = createMemorySource({ kind: 'note', content: 'note to delete' });
+  assert.ok(created);
+  const fetched = getMemorySource(created!.id);
+  assert.ok(fetched);
+  assert.equal(fetched!.content, 'note to delete');
+
+  const removed = deleteMemorySource(created!.id);
+  assert.ok(removed);
+  assert.equal(getMemorySource(created!.id), null);
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// memory-ingest
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-ingest: ingestNote persists a note source', async () => {
+  openDatabase(':memory:');
+
+  const result = await ingestNote('The CAPTURES.md pipeline runs on triage, not dispatch.', null, {
+    tags: ['captures'],
+    scope: 'project',
+    extract: false,
+  });
+
+  assert.ok(result.sourceId.startsWith('SRC-'));
+  assert.equal(result.duplicate, false);
+  assert.equal(result.kind, 'note');
+  assert.equal(result.extracted.length, 0);
+  assert.match(summarizeIngest(result), /no memories extracted/);
+
+  closeDatabase();
+});
+
+test('memory-ingest: ingestNote rejects empty input', async () => {
+  openDatabase(':memory:');
+
+  const result = await ingestNote('   ', null, { extract: false });
+  assert.equal(result.sourceId, '');
+
+  closeDatabase();
+});
+
+test('memory-ingest: ingestNote marks duplicates on replay', async () => {
+  openDatabase(':memory:');
+
+  const first = await ingestNote('same note body', null, { extract: false });
+  const second = await ingestNote('same note body', null, { extract: false });
+  assert.equal(first.sourceId, second.sourceId);
+  assert.equal(second.duplicate, true);
+
+  closeDatabase();
+});
+
+test('memory-ingest: ingestFile persists a file source', async () => {
+  openDatabase(':memory:');
+
+  const dir = mkdtempSync(join(tmpdir(), 'gsd-memory-ingest-'));
+  const file = join(dir, 'sample.md');
+  writeFileSync(file, '# Architecture\n\nWe use SQLite with WAL journaling.', 'utf-8');
+
+  try {
+    const result = await ingestFile(file, null, { tags: ['arch'], extract: false });
+    assert.ok(result.sourceId.startsWith('SRC-'));
+    assert.equal(result.kind, 'file');
+    assert.equal(result.title, 'sample.md');
+    assert.equal(result.uri, file);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+    closeDatabase();
+  }
+});
+
+test('memory-ingest: ingestFile rejects missing paths', async () => {
+  openDatabase(':memory:');
+
+  await assert.rejects(() => ingestFile('/no/such/file/exists.md', null, { extract: false }), /File not found/);
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// schema migration + scope/tags columns on memories
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-store schema: scope and tags columns exist on memories', () => {
+  openDatabase(':memory:');
+  const adapter = _getAdapter();
+  const info = adapter!.prepare('PRAGMA table_info(memories)').all();
+  const names = info.map((row: Record<string, unknown>) => row.name);
+  assert.ok(names.includes('scope'));
+  assert.ok(names.includes('tags'));
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/memory-maintenance.test.ts

@@ -0,0 +1,107 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { _getAdapter, closeDatabase, openDatabase } from '../gsd-db.ts';
+import {
+  createMemory,
+  decayStaleMemories,
+  enforceMemoryCap,
+  markUnitProcessed,
+} from '../memory-store.ts';
+import { createMemoryRelation, listRelationsFor } from '../memory-relations.ts';
+import { saveEmbedding, getEmbeddingForMemory } from '../memory-embeddings.ts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// enforceMemoryCap — cascade cleanup of embeddings and relations
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-cap: supersedes lowest-ranked memories and cascades cleanup', () => {
+  openDatabase(':memory:');
+
+  // Create 6 memories with descending confidence so the first is lowest.
+  createMemory({ category: 'pattern', content: 'weakest', confidence: 0.2 });
+  createMemory({ category: 'pattern', content: 'mid-1', confidence: 0.5 });
+  createMemory({ category: 'pattern', content: 'mid-2', confidence: 0.6 });
+  createMemory({ category: 'pattern', content: 'strong-1', confidence: 0.9 });
+  createMemory({ category: 'pattern', content: 'strong-2', confidence: 0.92 });
+  createMemory({ category: 'pattern', content: 'strongest', confidence: 0.95 });
+
+  saveEmbedding('MEM001', new Float32Array([1, 0, 0]), 'm');
+  saveEmbedding('MEM006', new Float32Array([0, 1, 0]), 'm');
+  createMemoryRelation('MEM001', 'MEM002', 'related_to');
+
+  // Cap at 5 — MEM001 should be superseded and its embedding + relations purged.
+  enforceMemoryCap(5);
+
+  const adapter = _getAdapter();
+  const row = adapter!
+    .prepare("SELECT superseded_by FROM memories WHERE id = 'MEM001'")
+    .get();
+  assert.equal(row?.['superseded_by'], 'CAP_EXCEEDED');
+  assert.equal(getEmbeddingForMemory('MEM001'), null);
+  assert.equal(listRelationsFor('MEM001').length, 0);
+
+  // MEM006 was not victimised — its embedding should still exist.
+  assert.ok(getEmbeddingForMemory('MEM006'));
+
+  closeDatabase();
+});
+
+test('memory-cap: is a no-op when count is already under the cap', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'one' });
+  createMemory({ category: 'pattern', content: 'two' });
+
+  enforceMemoryCap(10);
+
+  const adapter = _getAdapter();
+  const count = adapter!
+    .prepare("SELECT count(*) as cnt FROM memories WHERE superseded_by IS NULL")
+    .get();
+  assert.equal(count?.['cnt'], 2);
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// decayStaleMemories — returns list of decayed IDs
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-decay: returns decayed memory IDs', () => {
+  openDatabase(':memory:');
+
+  // Insert processed units — decayStaleMemories needs at least N rows.
+  const now = Date.now();
+  for (let i = 0; i < 21; i++) {
+    markUnitProcessed(`unit/${i}`, `file-${i}`);
+    // small spacing to create deterministic ordering
+    const row = _getAdapter()!
+      .prepare('UPDATE memory_processed_units SET processed_at = :ts WHERE unit_key = :key');
+    row.run({ ':ts': new Date(now + i * 1000).toISOString(), ':key': `unit/${i}` });
+  }
+
+  // Create memory with updated_at in the distant past
+  createMemory({ category: 'pattern', content: 'stale entry', confidence: 0.9 });
+  _getAdapter()!
+    .prepare("UPDATE memories SET updated_at = '2000-01-01T00:00:00Z' WHERE id = 'MEM001'")
+    .run({});
+
+  const decayed = decayStaleMemories(20);
+  assert.ok(decayed.includes('MEM001'));
+
+  // Confidence should have dropped.
+  const row = _getAdapter()!
+    .prepare("SELECT confidence FROM memories WHERE id = 'MEM001'")
+    .get();
+  assert.ok((row?.['confidence'] as number) < 0.9);
+
+  closeDatabase();
+});
+
+test('memory-decay: returns empty when there are fewer processed units than the threshold', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'fresh' });
+  const decayed = decayStaleMemories(20);
+  assert.deepEqual(decayed, []);
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/memory-relations.test.ts

@@ -0,0 +1,175 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { applyMemoryActions, createMemory, supersedeMemory } from '../memory-store.ts';
+import {
+  createMemoryRelation,
+  isValidRelation,
+  listRelationsFor,
+  removeMemoryRelationsFor,
+  traverseGraph,
+  VALID_RELATIONS,
+} from '../memory-relations.ts';
+import { executeGsdGraph } from '../tools/memory-tools.ts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Validation
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-relations: isValidRelation recognises the canonical set', () => {
+  for (const rel of VALID_RELATIONS) {
+    assert.ok(isValidRelation(rel));
+  }
+  assert.equal(isValidRelation('bogus'), false);
+  assert.equal(isValidRelation(null), false);
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// createMemoryRelation
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-relations: createMemoryRelation round-trips', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'architecture', content: 'auth lives in src/auth' });
+  createMemory({ category: 'pattern', content: 'jwt tokens signed with HS256' });
+
+  const ok = createMemoryRelation('MEM001', 'MEM002', 'elaborates', 0.9);
+  assert.equal(ok, true);
+
+  const relations = listRelationsFor('MEM001');
+  assert.equal(relations.length, 1);
+  assert.equal(relations[0].from, 'MEM001');
+  assert.equal(relations[0].to, 'MEM002');
+  assert.equal(relations[0].rel, 'elaborates');
+  assert.equal(relations[0].confidence, 0.9);
+
+  closeDatabase();
+});
+
+test('memory-relations: rejects self-loops and unknown memories', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'gotcha', content: 'only one memory exists' });
+
+  assert.equal(createMemoryRelation('MEM001', 'MEM001', 'related_to'), false);
+  assert.equal(createMemoryRelation('MEM001', 'MEM999', 'related_to'), false);
+  assert.equal(createMemoryRelation('MEM001', 'MEM002', 'bogus-rel' as never), false);
+
+  closeDatabase();
+});
+
+test('memory-relations: duplicate (from, to, rel) upserts instead of erroring', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'A' });
+  createMemory({ category: 'pattern', content: 'B' });
+
+  assert.equal(createMemoryRelation('MEM001', 'MEM002', 'related_to', 0.7), true);
+  assert.equal(createMemoryRelation('MEM001', 'MEM002', 'related_to', 0.9), true);
+
+  const relations = listRelationsFor('MEM001');
+  assert.equal(relations.length, 1);
+  assert.equal(relations[0].confidence, 0.9);
+
+  closeDatabase();
+});
+
+test('memory-relations: removeMemoryRelationsFor wipes both directions', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'A' });
+  createMemory({ category: 'pattern', content: 'B' });
+  createMemory({ category: 'pattern', content: 'C' });
+  createMemoryRelation('MEM001', 'MEM002', 'related_to');
+  createMemoryRelation('MEM003', 'MEM002', 'elaborates');
+
+  removeMemoryRelationsFor('MEM002');
+
+  assert.equal(listRelationsFor('MEM001').length, 0);
+  assert.equal(listRelationsFor('MEM002').length, 0);
+  assert.equal(listRelationsFor('MEM003').length, 0);
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LINK action via applyMemoryActions
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-relations: applyMemoryActions processes LINK actions', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'architecture', content: 'core lives in src/core' });
+  createMemory({ category: 'pattern', content: 'events flow through EventEmitter' });
+
+  applyMemoryActions([
+    { action: 'LINK', from: 'MEM001', to: 'MEM002', rel: 'related_to', confidence: 0.75 },
+    // unknown rel type — should be skipped silently
+    { action: 'LINK', from: 'MEM001', to: 'MEM002', rel: 'nonsense-rel' as never },
+  ]);
+
+  const relations = listRelationsFor('MEM001');
+  assert.equal(relations.length, 1);
+  assert.equal(relations[0].rel, 'related_to');
+
+  closeDatabase();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// traverseGraph + gsd_graph tool
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-relations: traverseGraph walks multi-hop edges', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'A' });
+  createMemory({ category: 'pattern', content: 'B' });
+  createMemory({ category: 'pattern', content: 'C' });
+  createMemoryRelation('MEM001', 'MEM002', 'related_to');
+  createMemoryRelation('MEM002', 'MEM003', 'depends_on');
+
+  const hop1 = traverseGraph('MEM001', 1);
+  assert.equal(hop1.nodes.length, 2);
+  assert.equal(hop1.edges.filter((e) => e.rel !== 'supersedes').length, 1);
+
+  const hop2 = traverseGraph('MEM001', 2);
+  assert.equal(hop2.nodes.length, 3);
+  assert.equal(hop2.edges.filter((e) => e.rel !== 'supersedes').length, 2);
+
+  closeDatabase();
+});
+
+test('memory-relations: traverseGraph still reports supersedes edges', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'convention', content: 'old style' });
+  createMemory({ category: 'convention', content: 'new style' });
+  supersedeMemory('MEM001', 'MEM002');
+
+  const graph = traverseGraph('MEM001', 1);
+  const ids = graph.nodes.map((n) => n.id).sort();
+  assert.deepEqual(ids, ['MEM001', 'MEM002']);
+  assert.ok(graph.edges.some((e) => e.rel === 'supersedes' && e.from === 'MEM001' && e.to === 'MEM002'));
+
+  closeDatabase();
+});
+
+test('memory-tools: gsd_graph returns LINK edges and filters by rel', () => {
+  openDatabase(':memory:');
+  createMemory({ category: 'pattern', content: 'alpha' });
+  createMemory({ category: 'pattern', content: 'beta' });
+  createMemory({ category: 'pattern', content: 'gamma' });
+  createMemoryRelation('MEM001', 'MEM002', 'related_to');
+  createMemoryRelation('MEM001', 'MEM003', 'contradicts');
+
+  const all = executeGsdGraph({ mode: 'query', memoryId: 'MEM001', depth: 1 });
+  assert.ok(!all.isError);
+  const allEdges = all.details.edges as Array<{ rel: string }>;
+  const relTypes = new Set(allEdges.map((e) => e.rel));
+  assert.ok(relTypes.has('related_to'));
+  assert.ok(relTypes.has('contradicts'));
+
+  const filtered = executeGsdGraph({ mode: 'query', memoryId: 'MEM001', depth: 1, rel: 'related_to' });
+  assert.ok(!filtered.isError);
+  const fEdges = filtered.details.edges as Array<{ rel: string; to: string }>;
+  assert.equal(fEdges.length, 1);
+  assert.equal(fEdges[0].rel, 'related_to');
+  assert.equal(fEdges[0].to, 'MEM002');
+
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/memory-store.test.ts

@@ -323,9 +323,9 @@ test('memory-store: schema includes memories table', () => {
   const viewCount = adapter.prepare('SELECT count(*) as cnt FROM active_memories').get();
   assert.deepStrictEqual(viewCount?.['cnt'], 0, 'active_memories view should exist');
 
-  // Verify schema version is 17 (ADR-011 P2 escalation columns included)
+  // Verify schema version is 20 (memory Phase 4 relations included)
   const version = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.['v'], 17, 'schema version should be 17');
+  assert.deepStrictEqual(version?.['v'], 20, 'schema version should be 20');
 
   closeDatabase();
 });