Skip to main content
The Search API provides powerful full-text and semantic search capabilities across your entire knowledge graph, including entities, observations, and relations.

​
Search Entities

Search across all content in a project with advanced filtering options. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/search/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "python AND flask",
    "retrieval_mode": "fts",
    "note_types": ["note", "spec"],
    "after_date": "2026-01-01T00:00:00Z"
  }'

​
Path Parameters

​
project_id
string
required
Project external UUID

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (1-indexed)
​
page_size
integer
default:"10"
Number of results per page (max 100)

​
Request Body

​
Primary Search Modes (use ONE)

​
text
string
Full-text search query. Supports boolean operators:
  • python AND flask - Both terms required
  • python OR django - Either term matches
  • python NOT django - First term but not second
  • (python OR flask) AND web - Grouping with parentheses
​
title
string
Search entity titles only
​
permalink
string
Exact permalink match
​
permalink_match
string
Glob-style permalink pattern (e.g., docs/*, specs/search*)

​
Search Filters (optional)

​
note_types
array
Filter by note types (e.g., ["note", "person", "spec"])
​
entity_types
array
Filter by entity types: entity, observation, or relation
​
after_date
string
Only return items updated after this date (ISO 8601 format)
​
metadata_filters
object
Structured frontmatter filters (e.g., {"status": "active", "priority": "high"})
​
tags
array
Filter by frontmatter tags (e.g., ["python", "web"])
​
status
string
Filter by frontmatter status field
​
retrieval_mode
string
default:"fts"
Search strategy:
  • fts - Full-text search (fast, keyword-based)
  • vector - Semantic search (meaning-based, requires embeddings)
  • hybrid - Combines FTS and vector search
​
min_similarity
number
Minimum similarity score for semantic search (0.0 to 1.0)

​
Response

​
results
array
Array of search results
​
current_page
integer
Current page number
​
page_size
integer
Results per page
​
has_more
boolean
True if more results are available

​
Example Response

{
  "results": [
    {
      "title": "Flask Web Framework",
      "type": "entity",
      "score": 0.95,
      "permalink": "frameworks/flask",
      "file_path": "frameworks/flask.md",
      "content": "# Flask Web Framework\n\nFlask is a lightweight Python web framework...",
      "matched_chunk": "Flask is a lightweight Python web framework that provides...",
      "entity_id": 123,
      "metadata": {
        "type": "spec",
        "tags": ["python", "web", "framework"],
        "status": "active"
      }
    },
    {
      "title": "Python Best Practices",
      "type": "entity",
      "score": 0.82,
      "permalink": "guides/python-best-practices",
      "file_path": "guides/python-best-practices.md",
      "content": "# Python Best Practices\n\nWhen building web applications with Flask...",
      "matched_chunk": "...building web applications with Flask or Django...",
      "entity_id": 456,
      "metadata": {
        "type": "note",
        "tags": ["python", "best-practices"]
      }
    }
  ],
  "current_page": 1,
  "page_size": 10,
  "has_more": false
}

​
Reindex Project

Rebuilds the search index from scratch for a project. This is a background operation. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/search/reindex \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
status
string
Always “ok”
​
message
string
Status message: “Reindex initiated”

​
When to Reindex

Reindexing is typically needed after:
  • Bulk imports or migrations
  • Database corruption or inconsistencies
  • Upgrading Basic Memory versions
  • Changing search configuration
Reindexing happens in the background and doesn’t block API requests. Search will continue using the old index until reindexing completes.

​
Search Strategies

​
Full-Text Search (FTS)

Keyword-based search using SQLite FTS5: 
{
  "text": "python web framework",
  "retrieval_mode": "fts"
}
Pros:
  • Fast performance
  • No additional setup required
  • Exact keyword matching
Cons:
  • Misses semantic matches
  • Requires exact word forms

​
Semantic Search (Vector)

Meaning-based search using embeddings: 
{
  "text": "building web applications",
  "retrieval_mode": "vector",
  "min_similarity": 0.7
}
Pros:
  • Finds conceptually similar content
  • Understands synonyms and context
  • Better for natural language queries
Cons:
  • Requires embedding generation (slower initial setup)
  • Higher computational cost
  • Requires semantic_search_enabled in config
Semantic search requires embeddings to be generated. Enable with:
basic-memory config set semantic_search_enabled true
Combines FTS and vector search for best results: 
{
  "text": "web development frameworks",
  "retrieval_mode": "hybrid"
}
Pros:
  • Balances speed and semantic understanding
  • Catches both exact and conceptual matches
  • Best overall accuracy
Cons:
  • Requires embeddings like vector search
  • Slightly slower than pure FTS

​
Boolean Search Examples

​
AND Operator

Find documents with ALL terms: 
{
  "text": "python AND flask AND tutorial"
}

​
OR Operator

Find documents with ANY term: 
{
  "text": "flask OR django OR fastapi"
}

​
NOT Operator

Exclude documents with specific terms: 
{
  "text": "python NOT django"
}

​
Complex Queries

Combine operators with parentheses: 
{
  "text": "(python OR javascript) AND (web OR mobile) NOT deprecated"
}

​
Filtering Examples

​
By Date Range

{
  "text": "deployment",
  "after_date": "2026-02-01T00:00:00Z"
}

​
By Note Types

{
  "text": "architecture",
  "note_types": ["spec", "design"]
}

​
By Tags

{
  "text": "performance",
  "tags": ["optimization", "production"]
}

​
By Metadata

{
  "text": "api",
  "metadata_filters": {
    "status": "active",
    "priority": "high",
    "team": "backend"
  }
}

​
Combined Filters

{
  "text": "authentication",
  "note_types": ["spec", "note"],
  "tags": ["security"],
  "after_date": "2026-01-01T00:00:00Z",
  "metadata_filters": {
    "status": "active"
  }
}

​
Error Responses

​
400 Bad Request

Semantic search disabled: 
{
  "detail": "Semantic search is disabled. Enable with semantic_search_enabled config."
}
Missing dependencies: 
{
  "detail": "Semantic search dependencies not installed. Run: pip install basic-memory[semantic]"
}
Invalid query: 
{
  "detail": "No search criteria provided"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us