[Bug]: octopoda_recall_similar returns 0 results for every query

[Dvalin21]

The octopoda_recall_similar MCP tool returns an empty result set for every query
regardless of matching content in the database.

How to reproduce:

1. Store a memory with octopoda_remember
2. Query with octopoda_recall_similar using text that should match
3. Observe count=0, items=[]

Tested queries against a database with 77+ memories:

• "kernel crash null pointer dereference" -> 0 results
• "octopoda verification test" -> 0 results
• "RAID storage" -> 0 results
• "octopoda recall_similar semantic search bug" -> 0 results

Expected behavior: semantic search returns semantically related memories.

Actual behavior: empty result set every time.

Root cause analysis:
The README documents that semantic search in local mode requires the
octopoda[ai] extra (33MB on-device embedding model). Without it,
recall_similar silently returns nothing instead of:
(a) raising an error saying the embedding model is not installed
(b) falling back to keyword/FTS5 search
(c) emitting a log warning

At minimum the function should:

1. Check whether the embedding model is available at call time
2. Return a clear error if it is not, or fall back to FTS5/LIKE matching
3. Never silently return empty results -- that makes the tool indistinguishable
   from "no matching content found" vs "search is completely non-functional"

Environment:
octopoda 3.1.3
synrix_runtime 3.1.0
SQLite (local mode, no OCTOPODA_API_KEY)
Linux x86_64

I'll send a fix if you agree on the approach.

[Dvalin21]

ROOT CAUSE UPDATE - exact file and line numbers.

The MCP tool at api/mcp_server.py:568 calls the WRONG function:

# Line 558-573:
@mcp.tool()
def octopoda_recall_similar(agent_id: str, query: str, limit: int = 10) -> dict:
    agent = _get_agent(agent_id)
    result, latency = _timed(lambda: agent.search(query, limit=limit))  # <-- LINE 568: calls prefix search

agent.search() at api/runtime.py:598 is a PREFIX/METADATA search:

def search(self, prefix: str, limit: int = 50) -> SearchResult:
    full_prefix = f"agents:{self.agent_id}:{prefix}"
    results = self.backend.query_prefix(full_prefix, limit=limit)

It prepends agents:{agent_id}: to the query and does a key prefix scan. A natural language query like "kernel crash null pointer dereference" becomes the prefix agents:opencode:kernel crash null pointer dereference, which matches NO keys. Always returns empty.

The actual semantic search method exists at api/runtime.py:621 but is NEVER CALLED from the MCP tool:

def recall_similar(self, query: str, limit: int = 10) -> SearchResult:
    # Has embedding model check, cloud fallback, and semantic_search backend call

Fix: change line 568 from:
result, latency = _timed(lambda: agent.search(query, limit=limit))
to:
result, latency = _timed(lambda: agent.recall_similar(query, limit=limit))

The recall_similar method already handles the case where embeddings are not installed
(returns empty result with a note field at lines 645-650). But at minimum the MCP should
try the actual semantic search path before giving up.

[RyjoxTechnologies]

Hey @Dvalin21, thanks again for the detailed walkthrough. Your line 568 analysis was correct for octopoda 3.1.3 (the version in your environment block). That specific routing bug, where the MCP tool called agent.search() instead of agent.recall_similar(), shipped fixed in 3.1.8.

Current state in 3.1.15 (just released today):

The integration adapter now does a three tier search strategy. It tries semantic first (via recall_similar, which needs the [ai] extra). If semantic returns empty, it falls back to FTS5 lexical search using the BM25 keyword index that already lives in the SQLite client. If both fail with a hard exception, it falls back to prefix search as a last resort.

def search(self, query, limit=10):
self._search_mode = "semantic"
try:
sr = self._rt.recall_similar(query, limit=limit)
items = self._extract_items(sr)
if items:
return items
fts_items = self._fts_fallback(query, limit)
if fts_items:
self._search_mode = "lexical"
return fts_items
return []
except Exception:
# try FTS5, then prefix, never silent
...
The MCP tool response now includes a mode field, set to one of "semantic", "lexical", or "prefix", so the caller can tell which engine actually returned the items. When results come back via the lexical fallback, the response carries an advisory pointing to pip install octopoda[ai] for higher quality matches. When both engines return empty, the advisory escalates to make it clear that the data really does not match (and that installing the [ai] extra would give fuzzier matching for future queries).

So your three asks from the original report are all closed:

(a) clear error when embeddings are not installed: yes, via the advisory field on the response.
(b) fall back to FTS5 or LIKE matching: yes, this ships in 3.1.15.
(c) never silently return empty without a signal: yes, both the mode field and the advisory field make every empty result explainable.

If you upgrade to 3.1.15 and re run your four probe queries against an agent with matching memories, you should now see real results either from semantic (if [ai] is installed) or from FTS5 (if not). I also pushed a live verification script at audit_verify_3_1_13.py in the repo that runs your audit probes against api.octopodas.com end to end. Current score against your priority list is 12 of 12 passing.

Really appreciate this report. Cheers.