AGY Memory Engine: Zero-dependency SQLite FTS5 fact store and MCP server

AGY Memory Engine, a zero-dependency SQLite FTS5 fact store and MCP server, delivers sub-2ms local retrieval with 0 MB extra RAM, serving as a persistent semantic backbone for Google Antigravity (agy) and autonomous agent frameworks. The engine partitions memory into three pillars—episodic, semantic, and procedural—to avoid vector DB bloat and context-stuffing, enabling exact, deterministic recall of core facts like IPs and preferences.

Lightweight, high-performance, standalone dynamic memory layer for Google Antigravity agy and autonomous agent frameworks. Inspired by Hermes Agent's 3-pillar memory architecture, using SQLite FTS5 for ultra-fast local retrieval <2ms and autonomous LLM background extraction for continuous long-term learning without prompt bloat. agy-memory-engine is designed as the persistent semantic backbone of a 24/7 personal autonomous agent stack: ┌────────────────────────────────────────┐ │ User on Telegram UI │ │ "Deploy staging update on prod-server" │ └──────────────────┬─────────────────────┘ │ ▼ ┌───────────────────────────────────┐ │ Telegram Gateway / Sidecar │ └───────┬───────────────────▲───────┘ │ │ 1. Pre-fetch│ │ 5. Telegram < 2ms │ │ Response ▼ │ ┌─────────────────────────────┐ │ │ AGY Memory Engine FTS5 │ │ │ - Staging IP: 192.168.1.50│ │ │ - SSH Port: 2222 │ │ │ - User Prefs & Hardware │ │ └──────────────┬──────────────┘ │ │ 2. Injected │ │ Ephemeral │ │ Context │ ▼ │ ┌──────────────────────────────────┴──┐ │ Google Antigravity CLI agy │ │ - Autonomous Execution │ │ - Tool Calls / Skills / MCP │ │ - Multi-Turn Reasoning │ └──────────────┬──────────────────────┘ │ │ 3. Output Stream ▼ ┌──────────────┐ │ Async Worker │ 4. Background sync-turn │ no delay │───► Extracts new facts & persists └──────────────┘ into memory.db without blocking UI To keep the agent razor-sharp across thousands of daily turns without prompt bloat or massive token bills, memory is partitioned into 3 distinct layers: | Pillar | Type | Scope & Lifecycle | Storage Mechanism | |---|---|---|---| Pillar 1 | Episodic / Working Context | Transient day-to-day conversation, ephemeral tasks, session scratchpad. Dies after task completion or referenced via logs. | In-flight context window, Google Tasks, Transcripts | Pillar 2 | Semantic / Long-Term Facts | Deterministic facts, server IPs, personal master data, credentials metadata, hardware specs, family profiles. Permanent & instantly searchable. | ~/.gemini/memory.db SQLite FTS5 + BM25 | Pillar 3 | Procedural / Skills & Rules | How to execute tasks: API definitions, security rules, playbooks, formatting standards. | System Rules user global , AGY Skills | Most LLM memory solutions today suffer from two extremes: Vector DB / Semantic RAG bloat: Embedding models, heavy C++/native dependencies Chroma, FAISS, PyTorch , slow cold-starts, vector drift, and poor keyword/exact match e.g. failing to cleanly recall exact IP addresses, port numbers, serials, or drug doses . Context-stuffing everything: Relying on huge 1M–2M context windows adds massive latency, increases token costs exponentially, and dilutes the agent's attention on long-running multi-turn sessions. Exact & Fast Fuzzy Vectors for Core Facts: When an agent needs your timezone, server IPs, hardware specs, or personal preferences, SQLite FTS5 with BM25 ranking delivers deterministic, exact results in < 2ms with 0 MB extra RAM . Telegram UX requires sub-second response starts: SQLite FTS5 pre-fetches relevant facts locally via standard library Python before the LLM begins streaming. Zero External Dependencies: Built entirely on Python’s standard library sqlite3 , re , difflib . Runs anywhere without pip install , wheel compilation issues, or Docker container overhead. Dynamic Pre-fetching without Prompt Bloat: Instead of dumping an entire personal wiki into the system prompt, agy-memory extracts key entities, fetches only the 3–5 relevant facts, and injects them as ephemeral context. Autonomous Background Learning & Compaction: Ingesting new memories is decoupled from the user interaction sync-turn . Over time, automated nightly compaction compact --apply deduplicates, resolves contradictions, and prunes stale data across all user accounts. ⚡ Blazing Fast Retrieval <2ms : Uses native SQLite FTS5 full-text indexing with BM25 ranking. 🔍 Typo & Fuzzy Fallback: Automatically handles misspelled terms and queries via difflib vocabulary matching. 🌐 Multilingual & German/English Stopword Filtering: Filters out noise and matches keywords cross-lingually. 🧠 Zero External Dependencies: Pure Python 3 standard library sqlite3 , re , difflib , argparse , json , subprocess . 🔌 Dual Interface: CLI: prefetch , sync-turn , add , list for shell scripts, cron jobs, and custom gateway integrations. MCP Server: Standard Model Context Protocol agy memory mcp.py exposing search memory , store memory , and list memories . ⚙️ Configurable & Portable: Resolves agy from $PATH automatically; database and cache paths configurable via environment variables AGY MEMORY DB , AGY MEMORY CACHE , AGY BIN . - Python 3.10+ standard library only, no pip install required - Google Antigravity CLI agy installed in $PATH or ~/.local/bin/agy optional, needed for automated sync-turn Add a fact python3 agy memory.py add --id "user.timezone" --category "preference" --fact "Timezone is UTC CET/CEST " --keywords "timezone zeit zeitzone time" List stored memories python3 agy memory.py list Query / Prefetch context for an upcoming prompt python3 agy memory.py prefetch "Wann beginnt das nächste Meeting?" Pass user input and assistant response to extract and persist new facts asynchronously: python3 agy memory.py sync-turn --user "Remember that our staging server IP changed to 192.168.1.150" --assistant "Understood, updated the staging IP." Over time, continuous background learning sync-turn can accumulate overlapping facts, fragmented notes, or outdated states. The compact command serves as an automated knowledge curator. Redundancy Elimination: Merges scattered mentions of the same subject into single, dense canonical entries. Contradiction & Drift Resolution: Replaces superseded states e.g. updated server IPs, new medication doses, changed configurations while preserving current accuracy. Zero Data Loss Guarantee: Retains 100% of concrete details exact dates, IDs, serial numbers, credentials, URLs . Keyword Enrichment: Generates fresh, multi-lingual search keywords DE/EN synonyms and misspellings to maximize FTS5 retrieval recall. Database Optimization: Rebuilds the FTS5 virtual table index and runs SQLite VACUUM to eliminate fragmentation. 1. Dry-run audit: Analyzes memories and displays a detailed diff/preview without writing changes python3 agy memory.py compact 2. Apply: Creates a timestamped backup in ~/.gemini/archive/, applies consolidations, and vacuums SQLite python3 agy memory.py compact --apply On multi-user servers where multiple local users e.g. family members or team members run independent Antigravity instances, memory databases are isolated under each user's home directory ~/.gemini/memory.db . The script scripts/agy-memory-compact-all.sh /sbolten/agy-memory-engine/blob/main/scripts/agy-memory-compact-all.sh automates maintenance across all users: Auto-Discovery: Scans /home/ for active user accounts with an existing ~/.gemini/memory.db . Permission Isolation: Executes the compaction strictly within each user's own permission boundary su - $username , ensuring backups and DB files retain correct ownership 0600 / 0700 . Plug & Play for New Users: Any newly created Linux user with an initialized memory database is automatically included without requiring manual configuration. Create /etc/cron.d/agy-memory-compact : /etc/cron.d/agy-memory-compact SHELL=/bin/bash PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin CRON TZ=UTC Run nightly at 04:00 AM before daily system backups 0 4 root /usr/local/bin/agy-memory-compact-all.sh /dev/null 2 &1 To connect the memory engine directly to AGY or any MCP-compatible agent, register the server in your MCP settings: { "mcpServers": { "memory": { "command": "python3", "args": "/path/to/agy-memory-engine/agy memory mcp.py" , "env": { "AGY MEMORY DB": "~/.gemini/memory.db" } } } } MIT License © 2026 Stephan Bolten