FusionAL Recall — Semantic Registry Search MCP

Recall wraps the FusionAL Solved-Issues Registry with semantic search, three-tier access control, and auto-migration.

Query your team's solved problems via MCP tools: recall() for semantic search, remember() to log new entries, list_recent() for recent issues, verify() to validate entry integrity.

Features

• Semantic Search: Query by problem description, not keyword. "claude desktop timeout" returns SI-001 even if you don't say "timeout" or "claude" exactly.
• Automatic Migration: Parse existing SOLVED-ISSUES.md markdown on first run; auto-assign SI-XXX IDs; populate SQLite.
• Three-Tier Access: personal (agent-only), project (team-scoped), public (shared community).
• Vector Storage: sentence-transformers + sqlite-vec for fast CPU-friendly embeddings.
• MCP Tools: recall(query, tier, limit), remember(symptoms, root_cause, fix, source, tags), list_recent(n), verify(si_id), get(si_id).

Architecture

SOLVED-ISSUES.md (markdown source)
         ↓
   [Migrate on startup]
         ↓
SQLite + sqlite-vec (embeddings index)
         ↓
FastMCP Server (port 8107)
         ↓
      [Tools]

SQL Schema

CREATE TABLE issues (
  si_id TEXT PRIMARY KEY,           -- SI-001, SI-002, etc.
  title TEXT NOT NULL,               -- one-line summary
  symptoms TEXT NOT NULL,
  root_cause TEXT NOT NULL,
  fix TEXT NOT NULL,
  source TEXT,                       -- session/task context
  tags TEXT,                         -- comma-separated
  verified_at TEXT,                  -- YYYY-MM
  created_at TEXT NOT NULL,          -- ISO 8601
  tier TEXT DEFAULT 'personal',      -- personal, project, public
  embedding BLOB NOT NULL            -- float32 vec (float-serialized)
);

Usage

Start the Server

python -m recall.server
# Listens on 0.0.0.0:8107

On first run, the server:

1. Reads SOLVED-ISSUES.md (path from SOLVED_ISSUES_PATH env var)
2. Parses SI-XXX markdown blocks
3. Generates embeddings for symptoms + root_cause + fix (combined text)
4. Inserts into SQLite + sqlite-vec index
5. Auto-assigns next SI-ID based on highest existing ID

MCP Tools

recall(query: str, tier: str = "personal", limit: int = 5) → List[Issue]

Semantic search. Returns issues matching the query, ranked by embedding similarity.

# Query: "claude desktop timeout"
# Returns: SI-001 (Claude Desktop server timeout above 8 servers)
results = await client.call_tool(
    name="recall",
    arguments={"query": "claude desktop timeout", "tier": "personal", "limit": 5}
)

remember(symptoms: str, root_cause: str, fix: str, source: str, tags: str) → Dict

Log a new issue. Returns the assigned SI-ID (e.g., SI-012).

result = await client.call_tool(
    name="remember",
    arguments={
        "symptoms": "My symptoms here",
        "root_cause": "Root cause",
        "fix": "Steps to fix",
        "source": "session context",
        "tags": "tag1,tag2"
    }
)
# Returns: {"si_id": "SI-012", "title": "...", "created_at": "..."}

list_recent(n: int = 10) → List[Issue]

Return the N most recently added issues.

recent = await client.call_tool(
    name="list_recent",
    arguments={"n": 10}
)

verify(si_id: str) → Dict

Check if an SI entry exists and is valid.

valid = await client.call_tool(
    name="verify",
    arguments={"si_id": "SI-001"}
)

get(si_id: str) → Dict

Retrieve full entry by SI-ID.

entry = await client.call_tool(
    name="get",
    arguments={"si_id": "SI-001"}
)

Deployment

Docker

docker build -t fusional-recall:latest .
docker run -p 8107:8107 \
  -e SOLVED_ISSUES_PATH=/mnt/kb/05-RECALL/SOLVED-ISSUES.md \
  -v /path/to/kb:/mnt/kb \
  fusional-recall:latest

Docker Compose

docker-compose up -d
# Recalls listens on localhost:8107
# recall.db volume persists embeddings across restarts

Testing

pytest tests/ -v

Tests validate:

• Migration: SOLVED-ISSUES.md parses correctly; all entries load into SQLite
• Recall: Semantic search returns SI-001 for query "claude desktop timeout"
• Remember: New entry is assigned SI-012, written to DB, queryable immediately
• Verify: SI-001 exists and validates; SI-999 does not
• Tier filtering: personal/project/public tiers are enforced

Environment Variables

Variable	Default	Purpose
RECALL_HOST	0.0.0.0	MCP server bind address
RECALL_PORT	8107	MCP server port
RECALL_DB_PATH	./recall.db	SQLite database file
EMBEDDING_MODEL	all-MiniLM-L6-v2	sentence-transformers model
DEFAULT_TIER	personal	Default access tier
SOLVED_ISSUES_PATH	../fusional-knowledge-base/05-RECALL/SOLVED-ISSUES.md	Path to registry markdown

License

MIT. See LICENSE.