Query: "authentication bug"
Keyword Match: Must contain both "authentication" AND "bug"
Semantic Match: Also finds "login error", "auth failure", "sign-in issue"

┌──────────────────────────────────────────────────────────────┐
│ User Query: "How does authentication work?"                  │
└──────────────────────────────────────────────────────────────┘
                            ↓
          ┌─────────────────┴─────────────────┐
          ↓                                   ↓
┌──────────────────────┐          ┌──────────────────────┐
│ Chroma Semantic      │          │ SQLite FTS5          │
│ Vector Similarity    │          │ Keyword Search       │
│                      │          │                      │
│ Finds conceptually   │          │ Finds exact/fuzzy    │
│ similar observations │          │ keyword matches      │
└──────────────────────┘          └──────────────────────┘
          ↓                                   ↓
          └─────────────────┬─────────────────┘
                            ↓
          ┌─────────────────────────────────┐
          │ Merge Results                   │
          │ - Deduplicate by ID             │
          │ - Sort by relevance + recency   │
          │ - Filter by 90-day window       │
          └─────────────────────────────────┘
                            ↓
          ┌─────────────────────────────────┐
          │ Return Top Matches              │
          │ Semantic + Keyword combined     │
          └─────────────────────────────────┘

CREATE TABLE observations (
  id INTEGER PRIMARY KEY,
  title TEXT,
  narrative TEXT,
  facts TEXT,
  concepts TEXT,
  files TEXT,
  type TEXT,
  projectPath TEXT,
  createdAt INTEGER
);

{
  ids: ["obs_12345"],
  embeddings: [[0.123, -0.456, ...]], // 384-dimensional vector
  documents: ["Title: Authentication flow\nNarrative: Implemented..."],
  metadatas: [{
    type: "feature",
    project: "claude-mem",
    timestamp: 1698765432000,
    concepts: "pattern,architecture"
  }]
}

"user authentication" → [0.12, -0.34, 0.56, ..., 0.78]
"login system"        → [0.15, -0.32, 0.54, ..., 0.81]
"database schema"     → [-0.45, 0.67, -0.23, ..., 0.12]

// Query embedding
query: "authentication bug"
query_vector: [0.14, -0.33, 0.55, ..., 0.79]

// Find observations with similar vectors
results = chroma.query(
  query_vector,
  n_results: 10,
  where: { timestamp: { $gte: now - 90_days } }
)

const ninetyDaysAgo = Date.now() - (90 * 24 * 60 * 60 * 1000);

// Chroma metadata filter
where: {
  timestamp: { $gte: ninetyDaysAgo }
}

// SQLite WHERE clause
WHERE createdAt >= ?

// Keyword-only (v4.x)
search_observations(query: "authentication")
// Returns: Observations containing "authentication"

// Hybrid semantic + keyword (v5.x)
search_observations(query: "authentication")
// Returns: Observations with "authentication" PLUS semantically similar:
//   - "login system"
//   - "user credentials"
//   - "session management"

// Uses Chroma to find best match, then builds timeline
get_timeline_by_query(
  query: "when did we implement the viewer UI?",
  mode: "auto",
  depth_before: 10,
  depth_after: 10
)

// Chroma finds: Observation #4057 "Web-Based Viewer UI for Real-Time Memory Stream"
// Returns: Timeline with 10 observations before + anchor + 10 after

python3 --version
# Should show: Python 3.7.x or higher

npm install
# Installs: chromadb (Python package via node-gyp bindings)

pip3 install chromadb

# Set Python path explicitly
export PYTHON=/usr/local/bin/python3
npm install

# Reinstall chromadb
pip3 install --upgrade chromadb

# Verify installation
python3 -c "import chromadb; print(chromadb.__version__)"

# Install build tools
# macOS: xcode-select --install
# Windows: npm install --global windows-build-tools
# Linux: apt-get install build-essential

// Proposed for future versions
{
  "env": {
    "CLAUDE_MEM_CHROMA_ENABLED": "true",          // Enable/disable Chroma
    "CLAUDE_MEM_CHROMA_PATH": "~/.claude-mem/chroma", // DB location
    "CLAUDE_MEM_EMBEDDING_MODEL": "default",       // Embedding model choice
    "CLAUDE_MEM_RECENCY_DAYS": "90",              // Recency window
    "CLAUDE_MEM_VECTOR_DIM": "384"                // Embedding dimensions
  }
}

{
  "env": {
    "CLAUDE_MEM_CHROMA_ENABLED": "false"
  }
}

~/.claude-mem/chroma/
├── chroma.sqlite3         # Chroma metadata database
└── index/                 # Vector index files
    └── *.bin              # Binary vector data

# Backup entire Chroma directory
cp -r ~/.claude-mem/chroma ~/.claude-mem/chroma.backup

# Restore from backup
rm -rf ~/.claude-mem/chroma
cp -r ~/.claude-mem/chroma.backup ~/.claude-mem/chroma

# Delete Chroma database
rm -rf ~/.claude-mem/chroma

# Restart worker to trigger full resync
npm run worker:restart

# Check logs for sync progress
npm run worker:logs

-- Delete observations older than 1 year
-- This will trigger Chroma resync on next startup
sqlite3 ~/.claude-mem/claude-mem.db \
  "DELETE FROM observations WHERE createdAt < strftime('%s', 'now', '-1 year') * 1000;"

import { ChromaSync } from './services/sync/ChromaSync';

const sync = new ChromaSync();
await sync.initialize();

// Query Chroma directly
const results = await sync.query({
  queryTexts: ["authentication implementation"],
  nResults: 10,
  where: {
    type: "feature",
    timestamp: { $gte: Date.now() - 90_days }
  }
});

console.log(results.ids, results.distances, results.documents);

// Future configuration
const sync = new ChromaSync({
  embeddingModel: "sentence-transformers/all-MiniLM-L6-v2", // Smaller, faster
  // or: "text-embedding-ada-002" (OpenAI, requires API key)
  // or: "all-mpnet-base-v2" (Higher quality, slower)
});

// Find observations by type and project
results = await sync.query({
  queryTexts: ["API design"],
  where: {
    $and: [
      { type: { $in: ["decision", "feature"] } },
      { project: "claude-mem" }
    ]
  }
});

// Find recent observations
results = await sync.query({
  queryTexts: ["database schema"],
  where: {
    timestamp: { $gte: Date.now() - 30_days }
  }
});

# Check Python installation
python3 --version

# Reinstall chromadb
pip3 install chromadb

# Restart worker
npm run worker:restart

# Increase Node.js heap size
export NODE_OPTIONS="--max-old-space-size=4096"

# Restart worker
npm run worker:restart