╔═══════════════════════════════════════════════════════════════╗
    ║                                                               ║
    ║   🧠  SEMANTIC MEMORY  🧠                                     ║
    ║                                                               ║
    ║   ┌─────────────────────────────────────────────────────┐     ║
    ║   │  "The palest ink is better than the best memory."  │     ║
    ║   │                          — Chinese Proverb          │     ║
    ║   └─────────────────────────────────────────────────────┘     ║
    ║                                                               ║
    ║   Vector embeddings + PGLite = Persistent agent learning     ║
    ║                                                               ║
    ╚═══════════════════════════════════════════════════════════════╝

┌─────────────────────────────────────────────────────────────────┐
│                        swarm-mail PGLite                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│   │   events    │  │    hive     │  │   memories + embeddings │ │
│   │   (stream)  │  │   (cells)   │  │   (vector search)       │ │
│   └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    pgvector extension                    │   │
│   │              (1024-dim cosine similarity)                │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │     Ollama      │
                    │ mxbai-embed-lg  │
                    │   (optional)    │
                    └─────────────────┘

bun add opencode-swarm-plugin

# Install Ollama (macOS)
brew install ollama

# Start Ollama server
ollama serve

# Pull embedding model (1024 dimensions)
ollama pull mxbai-embed-large

// Store a learning
semantic-memory_store({
  information: "OAuth refresh tokens need 5min buffer before expiry...",
  tags: "auth,tokens,oauth",
  metadata: JSON.stringify({ priority: "high" })
})

// Search by meaning
semantic-memory_find({
  query: "token refresh race condition",
  limit: 5,
  expand: true  // Full content, not truncated
})

// Get specific memory
semantic-memory_get({ id: "mem-abc123" })

// Validate memory (reset decay)
semantic-memory_validate({ id: "mem-abc123" })

// Remove outdated memory
semantic-memory_remove({ id: "mem-abc123" })

// List all memories
semantic-memory_list({ collection: "default" })

// Get statistics
semantic-memory_stats()

// Check Ollama health
semantic-memory_check()

semantic-memory_store({
  information: `OAuth refresh tokens need 5min buffer before expiry to avoid 
race conditions. Without buffer, token refresh can fail mid-request if expiry 
happens between check and use. Implemented with: 
if (expiresAt - Date.now() < 300000) refresh()`,
  tags: "auth,oauth,tokens,race-conditions",
  metadata: JSON.stringify({ 
    source: "debugging-session",
    files: ["src/auth/refresh.ts"]
  })
})

// Vector search (semantic similarity)
semantic-memory_find({
  query: "authentication token expiry",
  limit: 5,
  expand: true
})

// Full-text search (keyword matching)
semantic-memory_find({
  query: "OAuth refresh",
  fts: true
})

score = raw_score × 0.5^(age_days / 90)

// ❌ BAD: No context
semantic-memory_store({
  information: "Changed auth timeout to 5 minutes"
})

// ✅ GOOD: Full context
semantic-memory_store({
  information: `OAuth refresh tokens need 5min buffer before expiry to avoid 
race conditions. Without buffer, token refresh can fail mid-request if expiry 
happens between check and use. 

Root cause: Token validity check happens at request start, but actual API call 
happens after async operations. If token expires during those operations, 
request fails with 401.

Solution: if (expiresAt - Date.now() < 300000) refresh()

Affects: All API clients using refresh tokens.`,
  tags: "auth,oauth,tokens,race-conditions,api-clients"
})

// Before debugging auth issues
semantic-memory_find({ query: "authentication error 401", limit: 5 })

// Before architectural decisions
semantic-memory_find({ query: "event sourcing tradeoffs", limit: 5 })

import { migrateLegacyMemories } from "swarm-mail/memory";

// Migrate from ~/.semantic-memory to swarm-mail
const result = await migrateLegacyMemories({
  legacyDbPath: "~/.semantic-memory/db",
  targetDb: swarmMailDb,
  dryRun: false  // Set true to preview
});

console.log(`Migrated ${result.migrated} memories`);
console.log(`Skipped ${result.skipped} (already exist)`);
console.log(`Failed ${result.failed} (see errors)`);

CREATE TABLE memories (
  id TEXT PRIMARY KEY,           -- e.g., "mem-abc123"
  content TEXT NOT NULL,         -- The memory content
  metadata JSONB DEFAULT '{}',   -- Tags, source, etc.
  collection TEXT DEFAULT 'default',
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL
);

CREATE INDEX idx_memories_collection ON memories(collection);
CREATE INDEX idx_memories_created ON memories(created_at DESC);

CREATE TABLE memory_embeddings (
  id SERIAL PRIMARY KEY,
  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
  embedding vector(1024) NOT NULL,  -- pgvector type
  UNIQUE(memory_id)
);

CREATE INDEX idx_memory_embeddings_vector 
  ON memory_embeddings USING ivfflat (embedding vector_cosine_ops);

CREATE INDEX idx_memories_fts 
  ON memories USING gin(to_tsvector('english', content));

# Check Ollama status
ollama list

# Start Ollama if not running
ollama serve

# Pull model if missing
ollama pull mxbai-embed-large

-- Check index exists
SELECT indexname FROM pg_indexes WHERE tablename = 'memory_embeddings';

-- Rebuild if needed (run via swarm-mail migration)

// These use different databases!
const adapter1 = await getMemoryAdapter("/project/a");
const adapter2 = await getMemoryAdapter("/project/b");

    🧠 ═══════════════════════════════════════════════════════ 🧠
    ║                                                         ║
    ║   "Those who cannot remember the past are condemned    ║
    ║    to repeat it."  — George Santayana                  ║
    ║                                                         ║
    ║   Store your learnings. Search before solving.         ║
    ║                                                         ║
    🧠 ═══════════════════════════════════════════════════════ 🧠