rekal AGENTS.md

rekal: Agent Instructions

What this project is

rekal is a Model Context Protocol (MCP) server that gives LLMs persistent long-term memory. It uses hybrid search (FTS5 + vector + recency) in a single SQLite file. Python 3.11+, installed via pip install rekal, runs as a stdio MCP server.

Architecture

MCP Client
  │ stdio (JSON-RPC)
  │
  mcp_adapter.py          ← create_server() factory, lifespan (creates/closes DB)
  │
  └── tools/core.py       ← the 3 tools (build_context, store, delete) + register()
                            │
                    sqlite_adapter.py ← SqliteDatabase @dataclass, ALL SQL lives here
                            │
                            ├── SQLite (memories: content, project, tags, timestamps)
                            ├── FTS5 (full-text index, auto-synced via triggers)
                            └── sqlite-vec (vector index)

Key rules

• SqliteDatabase is a @dataclass holding the aiosqlite.Connection and ALL query methods. Every SQL statement lives here. No SQL in tool files.
• tools/core.py holds the tool functions as plain async functions plus register(mcp, readonly=...), which attaches them to a server. REKAL_READONLY=1 registers recall only.
• mcp_adapter.py exposes create_server(): builds the MCPServer with the right instructions, manages lifespan, and calls register.
• The MCP surface is deliberately minimal (3 tools). Admin operations (health, export, prune, recall) belong in the CLI (rekal/__main__.py), not new MCP tools.
• No dynamic SQL. SQL strings must be static literals. No f-strings, no string concatenation, no % formatting to build queries. Use subqueries and parameterized ? placeholders instead.

Re-expansion bar

Do not restore conversations, memory links, scratch/TTL, memory types, access counters, or extra MCP tools because they sound useful. Earlier versions carried all of that; benchmarks showed the structure cost tokens (fatter payloads, fatter instructions) without earning them back. Prefer improving injection quality, bench coverage, and write hygiene (skills/CLI) first.