{"title":"FTS5 Full-Text Search","slug":"fts5-search","category":"concepts","summary":"How Synapse uses SQLite FTS5 for sub-millisecond full-text memory search.","audience":["human","llm"],"tags":["concept","search","fts5","fulltext"],"difficulty":"advanced","updated":"2026-06-27","word_count":561,"read_minutes":3,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# FTS5 Full-Text Search\n\nSynapse uses FTS5 (Full-Text Search 5) for fast, flexible memory search. This\npage explains how it works and how to use it effectively.\n\n## What is FTS5?\n\nFTS5 is a SQLite extension (also available in PostgreSQL via extensions) that\nprovides full-text search capabilities. It:\n\n- Indexes text content for fast keyword search\n- Supports boolean operators (AND, OR, NOT)\n- Supports phrase matching with quotes\n- Supports prefix matching with `*`\n- Ranks results by relevance\n\nSynapse uses FTS5 to index all memory content, enabling sub-millisecond search\nacross thousands of memories.\n\n## How Synapse Uses FTS5\n\nWhen you `POST /memory`:\n\n1. Memory content is stored in the `memories` table\n2. Content is also inserted into the FTS5 virtual table\n3. FTS5 automatically tokenizes and indexes the content\n\nWhen you `GET /memory/search?q=...`:\n\n1. Synapse parses the query using FTS5 syntax\n2. Executes a `MATCH` against the FTS5 index\n3. Filters by `mind_id` (tenant isolation)\n4. Returns ranked results\n\n## Query Syntax\n\n### Simple keyword search\n\n```\n?q=docker\n```\n\nReturns memories containing \"docker\".\n\n### Multiple keywords (implicit AND)\n\n```\n?q=docker+swarm\n?q=docker%20swarm\n```\n\nReturns memories containing BOTH \"docker\" AND \"swarm\".\n\n### Phrase matching\n\n```\n?q=\"docker+swarm\"\n?q=%22docker%20swarm%22\n```\n\nReturns memories containing the exact phrase \"docker swarm\".\n\n### Prefix matching\n\n```\n?q=docker*\n```\n\nReturns memories containing words starting with \"docker\" (e.g. \"dockers\",\n\"dockerfile\", \"dockerize\").\n\n### Boolean OR\n\n```\n?q=docker+OR+kubernetes\n```\n\nReturns memories containing \"docker\" OR \"kubernetes\".\n\n### Boolean NOT\n\n```\n?q=docker+-swarm\n?q=docker+NOT+swarm\n```\n\nReturns memories containing \"docker\" but NOT \"swarm\".\n\n### Grouping\n\n```\n?q=(docker+OR+kubernetes)+-test\n```\n\nReturns memories containing \"docker\" or \"kubernetes\", but not \"test\".\n\n## Practical Examples\n\n### Find memories about a project\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=synapse+deployment\"\n```\n\n### Find exact phrase\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22\"\n```\n\n### Exclude test memories\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=production+-test\"\n```\n\n### Find by technology\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql\"\n```\n\n## Ranking\n\nFTS5 ranks results by relevance using BM25 algorithm. Factors:\n\n- Term frequency (how often the term appears)\n- Inverse document frequency (rarer terms rank higher)\n- Document length (shorter docs with the term rank higher)\n- Column weight (title > content)\n\nResults are returned in rank order (most relevant first).\n\n## Performance\n\n| Operation | Latency |\n|-----------|---------|\n| Search 100 memories | < 5ms |\n| Search 1,000 memories | < 10ms |\n| Search 10,000 memories | < 25ms |\n| Search 100,000 memories | < 100ms |\n\nFTS5 is highly optimized for read-heavy workloads.\n\n## Limitations\n\n### Stemming\n\nFTS5 doesn't do stemming by default. \"running\" and \"run\" are different terms.\n\n**Workaround:** Use prefix matching: `?q=run*`\n\n### Typo tolerance\n\nFTS5 doesn't support fuzzy matching. A typo will return no results.\n\n**Workaround:** Use semantic search (`/memory/semantic-search`) for conceptual\nmatching.\n\n### Stop words\n\nCommon words (the, a, an, is) are indexed but may not be useful for search.\nFTS5 handles this automatically.\n\n## FTS5 vs Semantic Search\n\n| Aspect | FTS5 | Semantic Search |\n|--------|------|-----------------|\n| Speed | Sub-millisecond | 50-100ms |\n| Matching | Exact keywords | Conceptual |\n| Typo tolerance | None | Some |\n| Stemming | None | Implicit |\n| Requires embeddings | No | Yes |\n| Best for | Specific terms | Concepts |\n\nUse FTS5 when you know the keywords. Use semantic search when you want\n\"memories about X\" where X is described differently.\n\n## Best Practices\n\n> [!TIP]\n> - **Use specific terms** — \"docker swarm\" beats \"container orchestration\"\n> - **Quote phrases** — `\"docker swarm\"` ensures phrase match\n> - **Use prefix for variations** — `deploy*` catches \"deploy\", \"deployment\", \"deploying\"\n> - **Exclude noise** — `-test` filters out test memories\n> - **Combine with tags** — `?q=docker&tag=production` narrows results\n\n## Next Steps\n\n- [Semantic Search](/docs/concepts/semantic-search)\n- [Memory API](/docs/api/memory)\n- [Memory Best Practices](/docs/guides/memory-best-practices)\n","content_html":"

FTS5 Full-Text Search

\n

Synapse uses FTS5 (Full-Text Search 5) for fast, flexible memory search. This\npage explains how it works and how to use it effectively.

\n

What is FTS5?

\n

FTS5 is a SQLite extension (also available in PostgreSQL via extensions) that\nprovides full-text search capabilities. It:

\n\n

Synapse uses FTS5 to index all memory content, enabling sub-millisecond search\nacross thousands of memories.

\n

How Synapse Uses FTS5

\n

When you POST /memory:

\n
    \n
  1. Memory content is stored in the memories table
    2. \n
  2. Content is also inserted into the FTS5 virtual table
    3. \n
  3. FTS5 automatically tokenizes and indexes the content
    4. \n
\n

When you GET /memory/search?q=...:

\n
    \n
  1. Synapse parses the query using FTS5 syntax
    2. \n
  2. Executes a MATCH against the FTS5 index
    3. \n
  3. Filters by mind_id (tenant isolation)
    4. \n
  4. Returns ranked results
    5. \n
\n

Query Syntax

\n

Simple keyword search

\n
?q=docker

Returns memories containing "docker".

\n

Multiple keywords (implicit AND)

\n
?q=docker+swarm\n?q=docker%20swarm

Returns memories containing BOTH "docker" AND "swarm".

\n

Phrase matching

\n
?q="docker+swarm"\n?q=%22docker%20swarm%22

Returns memories containing the exact phrase "docker swarm".

\n

Prefix matching

\n
?q=docker*

Returns memories containing words starting with "docker" (e.g. "dockers",\n"dockerfile", "dockerize").

\n

Boolean OR

\n
?q=docker+OR+kubernetes

Returns memories containing "docker" OR "kubernetes".

\n

Boolean NOT

\n
?q=docker+-swarm\n?q=docker+NOT+swarm

Returns memories containing "docker" but NOT "swarm".

\n

Grouping

\n
?q=(docker+OR+kubernetes)+-test

Returns memories containing "docker" or "kubernetes", but not "test".

\n

Practical Examples

\n

Find memories about a project

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"

Find exact phrase

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"

Exclude test memories

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=production+-test"

Find by technology

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"

Ranking

\n

FTS5 ranks results by relevance using BM25 algorithm. Factors:

\n\n

Results are returned in rank order (most relevant first).

\n

Performance

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationLatency
Search 100 memories< 5ms
Search 1,000 memories< 10ms
Search 10,000 memories< 25ms
Search 100,000 memories< 100ms
\n

FTS5 is highly optimized for read-heavy workloads.

\n

Limitations

\n

Stemming

\n

FTS5 doesn't do stemming by default. "running" and "run" are different terms.

\n

Workaround: Use prefix matching: ?q=run*

\n

Typo tolerance

\n

FTS5 doesn't support fuzzy matching. A typo will return no results.

\n

Workaround: Use semantic search (/memory/semantic-search) for conceptual\nmatching.

\n

Stop words

\n

Common words (the, a, an, is) are indexed but may not be useful for search.\nFTS5 handles this automatically.

\n

FTS5 vs Semantic Search

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AspectFTS5Semantic Search
SpeedSub-millisecond50-100ms
MatchingExact keywordsConceptual
Typo toleranceNoneSome
StemmingNoneImplicit
Requires embeddingsNoYes
Best forSpecific termsConcepts
\n

Use FTS5 when you know the keywords. Use semantic search when you want\n"memories about X" where X is described differently.

\n

Best Practices

\n

Next Steps

\n\n","urls":{"html":"/docs/concepts/fts5-search","text":"/docs/concepts/fts5-search?format=text","json":"/docs/concepts/fts5-search?format=json","llm":"/docs/concepts/fts5-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}