Search

Search Guide

Complete guide to the triple search system for querying project context and providing AI with historical decisions.

---

Triple Search System

Memory Journal provides three complementary search methods designed to help AI find relevant context across your project history:

1. Full-Text Search - Find exact keywords (e.g., "Redis caching decision")
2. Date Range Search - Find context from specific time periods (e.g., "what did we decide in Q3?")
3. Semantic Search - Find conceptually similar work (e.g., find "authentication" when searching for "user login")
4. Hybrid Search (RRF) - Combines Full-Text and Semantic using Reciprocal Rank Fusion for high-precision discovery.

Why This Matters for AI: Different types of questions need different search approaches. Combined, these methods ensure AI can always find relevant context, regardless of how you phrase the query. The search_entries tool now uses a heuristic auto mode by default to pick the best strategy, or can be forced into hybrid mode.

Tip

Cross-Database Search: When TEAM_DB_PATH is configured, searches automatically merge team results with a source marker, giving you results from both your personal journal and the team database in a single seamless query.

---

Full-Text Search

search_entries Tool

Fast keyword-based search with result highlighting - use this when you know the exact terms in past decisions or implementations.

Primary AI Use Case: Find specific technical decisions, architecture choices, or implementation details by exact keywords.

Basic Usage (Finding Past Decisions):

search_entries({
  query: "PostgreSQL decision", // Find that database architecture decision
  limit: 10,
  mode: "hybrid" // "auto" (default), "fts", "semantic", or "hybrid"
});

With filtering:

search_entries({
  query: "lazy loading startup",
  limit: 5,
  is_personal: false,
});

Output:

Found 3 entries:

#42 (technical_achievement) - 2025-10-04 16:45:30
Personal: False
Snippet: Implemented **lazy** **loading** for ML dependencies - **startup** improved...

#38 (research) - 2025-10-03 14:20:15
Personal: False
Snippet: Researching **lazy** initialization patterns for **performance**...

How It Works

Search Modes & Hybrid RRF:

The search_entries tool supports a mode parameter with four strategies:

• fts - Standard FTS5 keyword matching with BM25.
• semantic - Vector similarity search (diverting the query to ML embeddings).
• hybrid - Executes both FTS and Semantic searches concurrently, merging the results using Reciprocal Rank Fusion (RRF) for ultimate precision.
• auto (Default) - Uses a smart heuristic to analyze your query. It checks word length, lack of stop words, or specific formatting (like issue numbers, exact quotes) to automatically pick fts or semantic.

SQLite FTS5 Search:

• Content search via FTS5 MATCH with BM25 relevance ranking
• Special character escaping for safe queries
• Stop word filtering
• Rank-ordered results
• Query term highlighting

How Multi-Keyword Matching Works:

• Query is split on whitespace into individual terms
• FTS5 MATCH operator provides BM25 relevance ranking
• All terms must match for an entry to appear in results (implicit AND)
• Phrase matching with quotes and prefix matching with * are supported
• Matched terms are highlighted in result snippets
• Queries containing unsafe FTS5 characters fall back to LIKE matching

Note

This uses FTS5 for ranked full-text search. Boolean operators (AND/OR/NOT) are not supported directly, but phrase search ("exact phrase") and prefix matching (optim*) are supported. Queries containing unsafe FTS5 characters automatically fall back to LIKE matching. Use semantic_search for conceptual matching.

Examples:

// Multiple terms — all must appear in the entry
search_entries({ query: "database performance" });

// Specific technical term
search_entries({ query: "lazy loading" });

// Narrow by topic
search_entries({ query: "PostgreSQL connection pooling" });

Best Practices

Good queries:

• ✅ "performance optimization" - Specific
• ✅ lazy loading startup - Multiple keywords
• ✅ bug fix database - Related terms

Poor queries:

• ❌ the - Stop word
• ❌ a - Too common
• ❌ Single letter searches

---

Date Range Search

search_by_date_range Tool

Filter entries by date with additional criteria.

Basic Usage:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
});

With filters:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  tags: ["performance", "optimization"],
  entry_type: "technical_achievement",
  is_personal: false,
});

Output:

📅 Found 5 entries between 2025-10-01 and 2025-10-31:

**Entry #42** (technical_achievement) - 2025-10-04 16:45:30
Implemented lazy loading for ML dependencies...

**Entry #38** (research) - 2025-10-03 14:20:15
Researching lazy initialization patterns...

Use Cases

Sprint reviews:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-14",
  tags: ["sprint-15"],
});

Monthly summaries:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  is_personal: false,
});

Milestone tracking:

search_by_date_range({
  start_date: "2025-01-01",
  end_date: "2025-12-31",
  entry_type: "technical_achievement",
});

---

Semantic Search

semantic_search Tool

Find conceptually similar entries using ML embeddings.

Included by default in v3.0.0! No additional installation required - uses @huggingface/transformers in pure JavaScript.

Basic Usage:

semantic_search({
  query: "improving application startup time",
  limit: 5,
});

With threshold:

semantic_search({
  query: "performance optimization strategies",
  limit: 3,
  similarity_threshold: 0.5,
  is_personal: false,
});

Output:

🔍 Semantic Search Results for: 'improving application startup time'
Found 3 semantically similar entries:

**Entry #42** (similarity: 0.687)
Type: technical_achievement | Personal: False
Content: Implemented lazy loading for ML dependencies...

**Entry #38** (similarity: 0.521)
Type: research | Personal: False
Content: Researching lazy initialization patterns...

How It Works

Vector Embeddings:

• Model: all-MiniLM-L6-v2 (via @huggingface/transformers)
• Dimensions: 384
• Storage: SQLite BLOB + sqlite-vec index
• Similarity: Cosine similarity

First Use:

• Loads model (~100MB download)
• Takes ~5 seconds first time
• Subsequent searches: <1 second

Similarity Scores:

• 1.0 = Identical
• 0.7+ = Very similar
• 0.5-0.7 = Moderately similar
• 0.3-0.5 = Somewhat similar
• <0.3 = Not similar (filtered out)

Use Cases

Concept-based search:

// Find entries about performance even if they don't use that word
semantic_search({
  query: "making things faster and more efficient",
});

Find related work:

// Find similar implementations
semantic_search({
  query: "lazy loading pattern for improving startup performance",
});

Discover connections:

// Find entries you might have forgotten about
semantic_search({
  query: "debugging concurrent database access issues",
});

---

Importance-Sorted Search

All three search tools (search_entries, search_by_date_range, get_recent_entries) support a sort_by parameter that switches result ordering from chronological to importance-ranked.

Usage

// Search by importance instead of recency
search_entries({
  query: "authentication",
  sort_by: "importance",  // default: "timestamp"
  limit: 10,
});

// Recent entries ranked by importance
get_recent_entries({
  limit: 10,
  sort_by: "importance",
});

// Date range sorted by importance
search_by_date_range({
  start_date: "2026-01-01",
  end_date: "2026-03-31",
  sort_by: "importance",
});

How It Works

When sort_by: "importance" is used, each entry in the result set includes a computed importanceScore (0.0–1.0) based on four factors:

Factor	Weight	Calculation
Significance Type	30%	1.0 if significanceType is set
Relationship Count	35%	min(relationshipCount / 5, 1.0)
Causal Relationships	20%	min(causalCount / 3, 1.0)
Recency	15%	max(0, 1 − daysOld / 90)

The score is computed inline via SQL for FTS and date-range queries (zero N+1 overhead). For semantic and hybrid search modes, scores are computed post-fetch.

Response Format

When sort_by: "importance" is active, each entry includes the computed score:

{
  "entries": [
    {
      "id": 42,
      "content": "Architecture decision...",
      "importanceScore": 0.72,
      "significanceType": "decision"
    },
    {
      "id": 38,
      "content": "Research notes...",
      "importanceScore": 0.45
    }
  ]
}

When sort_by is omitted or set to "timestamp" (default), no importanceScore field appears and there is zero computational overhead.

Tip

When to use importance sorting: Use sort_by: "importance" when you want to surface the most structurally significant entries (decisions, milestones, highly-connected nodes) rather than just the most recent. This is especially useful for context retrieval before major decisions or when reviewing a large date range.

---

Search Comparison

Feature	Full-Text	Date Range	Semantic
Speed	Fast	Fast	Medium
Precision	High	High	Variable
Use Case	Keywords	Time-based	Concepts
Highlighting	Yes	No	No
Dependencies	None	None	Built-in ML
Filters	Personal	All filters	Personal
Sort by	Timestamp, Importance	Timestamp, Importance	Timestamp, Importance

---

Search Strategies

Strategy 1: Start with Full-Text

// 1. Try keywords first
search_entries({ query: "performance optimization" });

// 2. If too many results, add filters
search_entries({
  query: "performance optimization",
  is_personal: false,
});

// 3. If still too many, use date range
search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  tags: ["performance"],
});

Strategy 2: Use Semantic for Discovery

// When you're not sure of exact keywords
semantic_search({
  query: "strategies for reducing initialization overhead",
  limit: 10,
});

// Then use full-text on specific entries found

Strategy 3: Combine Multiple Searches

// 1. Date range to narrow down
const oct_entries = search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
});

// 2. Full-text within that period
search_entries({ query: "performance" });

// 3. Semantic to find related concepts
semantic_search({ query: "optimization techniques" });

---

Search Limitations

Note

Full-text search uses FTS5 with BM25 relevance ranking. Phrase search ("exact phrase") and prefix matching (optim*) are supported. Boolean operators (AND/OR/NOT) are not supported. Queries with special FTS5 characters fall back to LIKE matching.

For advanced matching needs, use semantic_search which finds conceptually related content using ML embeddings:

// Find entries about optimization even if they use different wording
semantic_search({
  query: "performance optimization techniques",
  similarity_threshold: 0.25,
  limit: 10,
});

See Semantic Search for full documentation.

---

Search Tips

Improve Full-Text Results

Use specific terms:

• ✅ "lazy loading pattern"
• ❌ "loading"

Multiple keywords:

• ✅ "database connection pool leak"
• ❌ "problem"

Use tags:

// More effective than text search for categorization
search_entries({ query: "optimization", is_personal: false });

Improve Semantic Results

Be descriptive:

• ✅ "techniques for reducing application startup latency"
• ❌ "faster startup"

Use context:

• ✅ "debugging concurrent database locking in multi-threaded Python applications"
• ❌ "database locks"

Adjust threshold:

// Strict (high quality, fewer results)
semantic_search({ query: "...", similarity_threshold: 0.6 });

// Loose (more results, lower quality)
semantic_search({ query: "...", similarity_threshold: 0.2 });

---

Troubleshooting

No Results

Check:

• Spelling of search terms
• Try broader terms
• Remove filters
• Check date range is correct
• Verify entries exist

Solutions:

• Try broader or shorter search terms
• Try semantic search
• Browse with get_recent_entries

Too Many Results

Solutions:

• Add more specific keywords
• Use filters (is_personal, entry_type)
• Use date range
• Increase similarity threshold (semantic)

Semantic Search Not Working

Check:

• Dependencies installed
• Server restarted after install
• Check logs for errors
• Try with test_simple first

---

Performance

Search Speed

Full-Text (FTS5):

• Small DB (<1000 entries): <10ms
• Medium DB (1000-10000): <50ms
• Large DB (>10000): <200ms

Date Range:

• Fast (indexed by timestamp)
• <10ms for most queries

Semantic:

• First search: ~5s (model load)
• Subsequent: 50-200ms
• Depends on index size

Optimization Tips

1. Use specific queries - Faster than broad searches
2. Limit results - Default 10 is good
3. Filter early - Use is_personal to reduce search space
4. Tag-based filtering - Very fast with indexes

---

AI-Powered Documentation Search

In addition to the built-in search tools, you can use the Adamic AI Search to search across all MCP server documentation:

• Coverage: All tools across MySQL MCP, PostgreSQL MCP, and Memory Journal MCP
• Intelligent Search: AI-powered semantic search across GitHub wikis, Gists, and documentation
• Quick Access: Search all three MCP servers in one place
• Real-World Examples: Find usage patterns and best practices

Use AI Search for:

• Finding tools across multiple MCP servers
• Discovering related functionality in other servers
• Cross-referencing documentation
• Getting comprehensive answers about the MCP ecosystem

---

Next: Explore Examples or learn about Tools.