GitHub - sbolten/agy-memory-engine: Lightweight SQLite FTS5 dynamic memory layer & MCP server for Google Antigravity (AGY) · GitHub
/" data-turbo-transient="true" />
Skip to content
Search/
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
sbolten
agy-memory-engine
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Latest commit
History<br>15 Commits<br>15 Commits
Folders and files<br>NameNameLast commit message<br>Last commit date<br>scripts
scripts
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
agy_memory.py
agy_memory.py
agy_memory_mcp.py
agy_memory_mcp.py
View all files
Repository files navigation
AGY Memory Engine
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 (<br>🌟 Key Features
⚡ Blazing Fast Retrieval (🔍 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).
🚀 Quick Start
1. Requirements
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)
2. Manual Fact Management (CLI)
# Add a fact<br>python3 agy_memory.py add --id "user.timezone" --category "preference" --fact "Timezone is Europe/Zurich (CET/CEST)" --keywords "timezone zeit zeitzone zurich schweiz"
# List stored memories<br>python3 agy_memory.py list
# Query / Prefetch context for an upcoming prompt<br>python3 agy_memory.py prefetch "Wann beginnt das Meeting in Zürich?"
3. Dynamic Conversation Turn Syncing
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."
4. Compaction, Deduplication & Knowledge Maintenance (compact)
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.
🎯 Why Use Memory Compaction?
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<br>python3 agy_memory.py compact
# 2. Apply: Creates a timestamped backup in ~/.gemini/archive/, applies consolidations, and vacuums SQLite<br>python3 agy_memory.py compact --apply
👥 Multi-User Nightly Maintenance (scripts/agy-memory-compact-all.sh)
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:
How it works:
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.
Deployment via System Cron:
Create /etc/cron.d/agy-memory-compact:
/dev/null...