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** with0 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 withoutpip 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 viadifflib
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
) exposingsearch_memory
,store_memory
, andlist_memories
.
⚙️ Configurable & Portable: Resolvesagy
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 automatedsync-turn
)
python3 agy_memory.py add --id "user.timezone" --category "preference" --fact "Timezone is UTC (CET/CEST)" --keywords "timezone zeit zeitzone time"
python3 agy_memory.py list
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 SQLiteVACUUM
to eliminate fragmentation.
python3 agy_memory.py compact
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 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
:
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
CRON_TZ=UTC
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