Sign in Subscribe

Uteke v0.12.0: Full-Text Search Inside Documents

Uteke v0.12.0: Full-Text Search Inside Documents

Uteke v0.12.0: Full-Text Search Inside Documents (Not Just Titles)

Semantic search is good at finding things that mean roughly the same thing as your query. Ask for "authentication patterns" and it returns memories about login flows, OAuth, and session management.

But semantic search is bad at exact phrases. If you search for salience_weight or room_documents or a specific error message buried in a 2,000-word document, vector similarity will not help you. You need keyword search.

That is what FTS5 gives you. And in Uteke v0.12.0, it now works on document content, not just titles.

What changed

Before v0.12.0, Uteke's FTS5 index covered two columns in the documents table: title and slug. If you wrote a detailed architecture spec titled "Sprint 12 Planning", searching for "rate limiting strategy" (a phrase buried in paragraph 14) returned zero results.

The title did not contain those words. The slug did not either. The full document body did, but FTS5 was not looking there.

Now FTS5 indexes the content column too. Every word in every document is searchable.

# This now works (previously: no results)
uteke doc search "rate limiting strategy"

Why this matters

Uteke stores two types of data: memories and documents. Memories are short snippets: facts, preferences, decisions. Documents are longer: architecture specs, API references, onboarding guides, meeting notes.

For memories, FTS5 on title + tags was enough. Memories are short, so the title usually captures the key terms.

Documents are different. A single document can be thousands of words. The important phrase might be a function name, a config key, or a single sentence in the middle of a technical explanation. Title-only search missed all of it.

With content indexing, you can now:

  • Search for a specific config key (salience_weight) across all documents
  • Find which document mentions a particular API endpoint
  • Locate a decision buried in meeting notes by searching for a project name or error message
  • Combine with room linking: create a room for "sprint-planning", link your architecture spec and API design docs, then search across all of them with one query

How the migration works

The tricky part was upgrading existing databases without data loss.

The old FTS5 virtual table had two columns: title and slug. The new one has three: title, slug, and content. SQLite does not support ALTER TABLE on FTS5 virtual tables. You cannot add a column to an existing FTS5 index.

So the migration recreates the table:

  1. Detect old schema: Check if the FTS5 table is missing the content column using pragma_table_info()
  2. Back up data: Read all existing documents from the base table
  3. Drop and recreate: Drop the old FTS5 virtual table, create a new one with all three columns
  4. Backfill: Re-insert all documents into the new FTS5 index
  5. Verify: Row counts match between base table and FTS5 index

All of this runs automatically on first launch after upgrading to v0.12.0. No manual steps, no scripts to run, no downtime.

Fresh databases get the 3-column FTS5 index from the initial schema. No migration needed.

Uteke supports both FTS5 (keyword) and vector (semantic) search, plus a hybrid mode that combines them. Here is when to use each:

Use FTS5 (keyword search) when: - You know the exact phrase: a function name, config key, error message - You want to find every document that mentions a specific term - Precision matters more than recall

Use vector search when: - You want concepts, not exact words: "authentication" finds login, OAuth, sessions - Your query is vague: "something about caching" - You want results that are semantically similar even if the words differ

Use hybrid search when: - You want the best of both: exact matches ranked higher, but semantic matches included - You are building a general-purpose search interface

# FTS5 keyword search
uteke doc search "rate limiting"

# Vector semantic search
uteke search "how do we handle API throttling"

# Hybrid (both combined with RRF)
uteke recall "rate limiting strategy" --hybrid

What else is in v0.12.0

Beyond FTS5 content search, this release adds:

  • 4 new room-document tools for MCP and CLI: link documents to rooms, unlink them, list documents in a room, and list rooms for a document. Previously only available via HTTP API.
  • Windows PowerShell installer: One-command install for Windows users (irm https://raw.githubusercontent.com/codecoradev/uteke/main/install.ps1 | iex). Contributed by @KazamiHazaki.
  • 5 bug fixes for silent data corruption issues. Covered in a separate post: 5 Bugs That Silently Corrupted Memory Data.

By the numbers: 432 tests passing, 35 MCP tools (up from 31), 61 HTTP endpoints, 75 CLI commands, binary size unchanged at 12 MB.

Upgrade

# Existing install: re-run the installer
curl -fsSL https://raw.githubusercontent.com/codecoradev/uteke/main/install.sh | sh

# Or build from source
git pull && cargo build --release --workspace

Schema migration runs automatically on first launch. Your existing documents get indexed immediately.

Full release notes: github.com/codecoradev/uteke/releases/tag/v0.12.0