接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
Hardening branch: see runtime setup and audit coverage. Automatic extraction now requires an explicitly configured tool-free chat-completions endpoint. It no longer launches an unrestricted AGY agent. Failed extraction retains pending turns. Schema upgrades run on first engine access; restart all clients together for rollout.
Lightweight SQLite FTS5 dynamic memory layer & MCP server for Google Antigravity (AGY)
Lightweight, high-performance, standalone dynamic cognitive memory layer for Google Antigravity (
agy) and autonomous agent frameworks.
Inspired by Hermes Agent's multi-pillar memory architecture, using SQLite FTS5 for ultra-fast local retrieval (<2ms), multilingual compound sub-token decomposition & morphological stemming (DE, EN, FR, IT, ES, NL, SV), relational entity linking, and autonomous background queue workers with calm-memory session debouncing.
.env)agy-memory-engine acts as the persistent semantic backbone across all client interfaces (Telegram, Terminal CLI, Web Cockpit, IDE):
┌────────────────────────────────────────────────────────┐
│ Omni-Channel Interfaces (Telegram, CLI, Web, IDE) │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│ Global AGY Stop-Hook (hooks.json) │
│ • Enqueues turn in < 1ms to turn_queue.db │
│ • Zero latency impact on active conversations │
└─────────────────────────┬──────────────────────────┘
│
▼ (5m Idle OR 15m Timeout)
┌────────────────────────────────────────────────────┐
│ Calm Memory Worker (memory_worker.py) │
│ • Batches full conversation into 1 LLM pass │
│ • Single consolidated Telegram status update │
│ • Loop prevention (AGY_INTERNAL_INVOCATION=1) │
└─────────────────────────┬──────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│ 4-Layer Cognitive Memory (~/.gemini/memory.db) │
│ • Layer 1: Atomic Facts (memories) │
│ • Layer 2: Narrative Episodes (episodes) │
│ • Layer 3: Experiential Learnings (learnings) │
│ • Layer 4: Relational Entity Graph (links) │
└────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ ~/.gemini/memory.db │
├───────────────────┬────────────────────────────┬────────────────────────────┬───────────────┤
│ Layer 1: Facts │ Layer 2: Narrative Dossiers│ Layer 3: Learnings │ Layer 4: Graph│
│ (`memories`) │ (`episodes`) │ (`learnings`) │(`entity_links`)
├───────────────────┼────────────────────────────┼────────────────────────────┼───────────────┤
│ - Server IPs/ports│ - Background histories │ - Rules of thumb, lessons │ - Directional │
│ - Hardware specs │ - Stances & sentiment │ - Tested heuristics │ relations │
│ - Master data │ - Lifecycle status decay │ - Contextual guidelines │ (hosted_on, │
│ - Exact BM25 match│ (active->cooling->past) │ - Decision rationale │ owns, etc.)│
└───────────────────┴────────────────────────────┴────────────────────────────┴───────────────┘
In version 2.0/2.1, agy-memory-engine deliberately avoided external, resource-heavy vector databases (such as Chroma, Milvus, or Qdrant) and PyTorch bloat (~500MB RAM, 150ms latency) to stay ultra-lightweight.
The limitation of pure keyword / FTS5 search: Pure FTS5 struggles with vocabulary mismatch: If a user asks in everyday conversational language about "preventing data loss during disk cleanup", while the database stores the heuristic "Deletions of any kind require explicit approval (deletion protection)", pure FTS5 keyword matching returns exactly 0 results.
The solution starting in v2.2.0: In-Process Hybrid Search (sqlite-vec + FastEmbed) Instead of introducing a heavy server backend, v2.2.0 combines the best of both worlds:
sqlite-vec): Runs natively in C directly inside the SQLite process (SIMD-accelerated, zero daemon, zero network hop).fastembed): Powered by ONNX Runtime with sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 (384 dimensions, ~9ms inference time, outstanding multilingual semantics).memory_worker.py) and MCP storage tools index vectors transparently in the background; SQLite cascade triggers handle deletions automatically.Get up and running from zero to autonomous memory in 5 minutes.
Clone the repository and install the lightweight Python dependencies (no PyTorch, no heavyweight vector DBs needed):
git clone https://github.com/HydStAn/agy-memory-engine.git
cd agy-memory-engine
# Optional: set up your environment configuration
cp .env.example .env
The database (~/.gemini/memory.db) will be automatically initialized with all FTS5 virtual tables on first run!
The easiest way to see what's happening and test queries is the built-in live dashboard:
# Start the web UI on port 8085
python3 agy_memory.py ui --port 8085
Open http://localhost:8085 in your browser. You can:
You can seed your agent's memory directly from the terminal:
# 1. Add an atomic fact (Layer 1)
python3 agy_memory.py add --id "infra.server.ip" --category "infra" --fact "Home server IP is 192.168.1.100" --keywords "home server ip host"
# 2. Add a personal learning / heuristic (Layer 3)
python3 agy_memory.py add-learning --id "workflow.email.style" --category "communication" --insight "Keep email replies strictly under 3 bullet points." --keywords "email communication reply rule"
# 3. Test sub-millisecond prefetch (< 2ms)
python3 agy_memory.py prefetch "server"
Add the memory engine as an MCP tool server so your agent can actively search and store knowledge:
# For Claude Code:
claude mcp add memory python3 $(pwd)/agy_memory_mcp.py
# Or in your MCP config JSON (~/.gemini/antigravity-cli/mcp_config.json or Claude Desktop):
{
"mcpServers": {
"memory": {
"command": "python3",
"args": ["/path/to/agy-memory-engine/agy_memory_mcp.py"]
}
}
}
GEMINI.md or CLAUDE.md)Add a simple memory rule to your global agent instructions (e.g. ~/.gemini/config/GEMINI.md, CLAUDE.md, or your project's system prompt) so your agent knows when to query memory:
## Long-Term Memory
- Before answering questions regarding personal preferences, server IPs, hardware, or past projects, call `search_memory` or run `agy_memory.py prefetch "<topic>"`.
- When the user states a new permanent fact or personal rule, persist it using `store_memory` or `record_learning`.
To have the memory engine automatically learn from your conversations without you lifting a finger:
~/.gemini/config/hooks.json (see Autonomous Background Pipeline).*/5 * * * * python3 /path/to/agy-memory-engine/memory_worker.py).# Multi-Layer Prefetch (< 2ms)
python3 agy_memory.py prefetch "Hundeversicherung"
# Add Layer 1 Fact
python3 agy_memory.py add --id "infra.server.ip" --category "infra" --fact "Home server IP is 192.168.1.50" --keywords "server host ip home"
# Add Layer 2 Episode
python3 agy_memory.py add-episode --id "travel.iceland2027" --topic "travel" --title "Laugavegur Trekking" --narrative "Hut booking watchdog active for July 2027." --status "active" --keywords "island laugavegur"
# Add Layer 3 Learning
python3 agy_memory.py add-learning --id "travel.flights.cdp" --category "travel" --insight "Use CDP browser for Google Flights to avoid bot-blocking." --keywords "google flights bot cdp"
# Link Entities in Graph
python3 agy_memory.py link --source "service.immich" --target "infra.server.ip" --relation "hosted_on"
# Optimize & Decay Maintenance
python3 agy_memory.py optimize --apply
# Migrate Database from v2.0 to v2.1 (Taxonomies, Relations, Graph Pruning)
python3 agy_memory.py migrate --dry-run
python3 agy_memory.py migrate
The engine includes a native FastMCP server (agy_memory_mcp.py) that equips autonomous AI agents (Antigravity, Claude, Cursor, OpenCode) with explicit memory reading and writing capabilities:
Add to your MCP settings file (e.g. ~/.gemini/antigravity-cli/mcp_config.json or Claude/Cursor config):
{
"mcpServers": {
"memory": {
"command": "python3",
"args": ["/opt/agy-memory-engine/agy_memory_mcp.py"],
"env": {
"AGY_MEMORY_DB": "~/.gemini/memory.db"
}
}
}
}
agy-memory-engine is designed to work in synergy with the Antigravity Telegram Bot (antigravity-cli-telegram-bot) to form a completely autonomous, mobile memory pipeline:
📱 Mobile User in Telegram (Voice, Text, Photos, Topics)
│
▼
🤖 AGY Telegram Bot (/opt/agy-telegram-bot)
│ (Executes standard agy prompt with --add-dir)
▼
⚡ AGY Global Stop-Hook (~/.gemini/config/hooks.json -> scripts/auto_sync_hook.py)
│ (Enqueues turn in <1ms to turn_queue.db, resolves Telegram topic/chat ID)
▼
🧠 Calm Memory Worker (memory_worker.py)
│ (Debounces 5m idle / 15m timeout, batches conversation into 1 LLM pass)
▼
💾 SQLite FTS5 Memory Store (~/.gemini/memory.db)
│
▼
📲 Instant Status Notification back to Telegram Topic / Chat
"🧠 Autonomous memory updated (1 fact, 1 learning)
• ➕ Home server IP is 192.168.1.50
• ➕ Use CDP browser for Google Flights"
< 1ms, ensuring the Telegram Bot responds instantly without waiting for memory extraction.chat_id and message_thread_id, routing notifications directly back into the relevant topic thread.AGY_INTERNAL_INVOCATION=1 with prompt marker guards to prevent recursive agent loops..env)All engine parameters, database locations, LLM model choice, and debounce thresholds can be configured via .env (or environment variables). A ready-to-use template is provided in .env.example:
# Copy template to .env
cp .env.example .env
# ==============================================================================
# AGY Memory Engine - Configuration File
# ==============================================================================
# LLM model used for background memory extraction & consolidation
AGY_MEMORY_MODEL=gemini-3.8-flash-low
# SQLite Database Storage Paths
AGY_MEMORY_DB=~/.gemini/memory.db
AGY_TURN_QUEUE_DB=~/.gemini/turn_queue.db
# Calm-Memory Debounce Settings (in seconds)
AGY_MEMORY_INACTIVITY_SECONDS=300 # 5 minutes idle threshold
AGY_MEMORY_MAX_WAIT_SECONDS=900 # 15 minutes max timeout
# Telegram Notification Recipient (optional: your numeric Telegram user or group ID)
AGY_MEMORY_TELEGRAM_CHAT_ID=your_telegram_chat_id_here
# Path to Antigravity CLI binary
AGY_BIN=agy
# Real-Time Debug Dashboard (Web UI)
AGY_MEMORY_DEBUG_DASHBOARD=true
AGY_MEMORY_DASHBOARD_PORT=8085
AGY_MEMORY_DASHBOARD_HOST=127.0.0.1
# Dashboard Authentication: set custom token or let engine auto-generate in ~/.gemini/dashboard.token
AGY_MEMORY_DASHBOARD_TOKEN=your_secure_dashboard_token_here
# Remote access (VPN, Tailscale, LAN): specify allowed hostnames and private networks
AGY_MEMORY_DASHBOARD_ALLOWED_HOSTS=my-node.ts.net,*.ts.net
AGY_MEMORY_DASHBOARD_ALLOW_PRIVATE_NETWORKS=true
# Optional: trusted OpenAI-compatible chat-completions URL for tool-free HTTP extraction.
# If unset (default), the engine gracefully falls back to native Antigravity CLI (agy --print).
AGY_MEMORY_INFERENCE_URL=
AGY_MEMORY_INFERENCE_MODEL=
AGY_MEMORY_INFERENCE_KEY=
# Jev relevance gate: one evaluation-model call per retrieval drops memory
# candidates that do not serve the request. Fail-open: without a key or on any
# error every candidate is kept. Key falls back to ~/.config/agy/sage.env.
AGY_JEV_API_KEY=
AGY_MEMORY_JEV_GATE=true
AGY_MEMORY_JEV_GATE_FLOOR=0.75
AGY_MEMORY_JEV_GATE_TIMEOUT=6
# Skip the call only when the candidate set is tiny AND short.
AGY_MEMORY_JEV_GATE_MIN_ITEMS=3
AGY_MEMORY_JEV_GATE_MIN_CHARS=600
Retrieval results pass through one evaluation-model call before they reach the agent. Each candidate is scored against the request in a single batched question set; candidates below AGY_MEMORY_JEV_GATE_FLOOR are dropped. This keeps unrelated facts, episodes, and learnings out of the agent context. The gate covers both search_memory and prefetch.
The call is skipped when the candidate set is smaller than AGY_MEMORY_JEV_GATE_MIN_ITEMS and shorter than AGY_MEMORY_JEV_GATE_MIN_CHARS. Many small candidates still get gated. Every failure mode fails open: a missing key, a timeout, or an unparseable answer keeps all candidates.
A zero-dependency, standalone live web dashboard is included to inspect, search, and monitor memory state in real time:
vis-network), and lazy tab rendering for instant mobile & desktop loads.The dashboard is protected by authentication tokens for all viewing and mutation endpoints:
~/.gemini/dashboard.token (permissions 0600, user-only)..env:.env via AGY_MEMORY_DASHBOARD_TOKEN=your-secret-token.?token=<your_token> to the URL on your first visit:
http://localhost:8085/?token=your_secure_dashboard_token_here
# Or over Tailscale:
https://<your-tailscale-node>.ts.net:8085/?token=your_secure_dashboard_token_here
localStorage, so subsequent reloads and visits do not require re-entering it.Authorization: Bearer <your_token>.# Via CLI command
python3 agy_memory.py ui --port 8085
# Or directly via standalone runner
python3 dashboard.py --port 8085
# Or via systemd background user service
systemctl --user start agy-memory-dashboard.service
To enable 100% autonomous background learning without manual intervention, configure the AGY Lifecycle Hook and the Linux Crontab:
~/.gemini/config/hooks.json)Registers the transcript collector on every agent turn stop:
{
"memory-auto-sync": {
"enabled": true,
"Stop": [
{
"type": "command",
"command": "python3 /opt/agy-memory-engine/scripts/auto_sync_hook.py",
"timeout": 15
}
]
}
}
crontab -e)# Process pending memory queue every 5 minutes (debounced)
*/5 * * * * python3 /opt/agy-memory-engine/memory_worker.py >/dev/null 2>&1
# Nightly deterministic maintenance only (04:30); semantic consolidation is opt-in
30 4 * * * python3 /opt/agy-memory-engine/agy_memory.py optimize --apply >/dev/null 2>&1
python3 -m unittest discover tests/ -v
# Ran 229 tests (OK)
consolidate_learnings() directly into optimize_db(), enabling seamless, automated consolidation during nightly maintenance (04:30 Uhr via cron) and autonomous worker cycles.prune_stale_calendar_facts() into a unified ephemeral fact lifecycle engine.%.flug_%, %.hotel_%, %.hammam_%, %.rueckreise_%, shopping.%order_%) with past dates (>14 days grace window) and automatically purges them, preventing fact-store dilution while strictly preserving long-term dates (medical, contracts, future bookings).agy_memory.py to 3 core triggers (user corrections, explicit rules/heuristics, and stable personal preferences), eliminating routine technical debugging noise.watchdog_memory_learnings.py to measure incoming learning noise dynamically against the latest consolidation_log timestamp.~/.gemini/memory.env overrides over project defaults.CANONICAL_LEARNING_CATEGORIES with dedicated domains: ux, dev, infra, and media, relieving the catch-all architecture bucket.ui_ux -> ux).CANONICAL_RELATIONS from 26 to 32 expressive link types: documents, configures, applies_to, resolves, targets, supports.documented_by, configured_by, resolved_by, targeted_by, supported_by, used_by, stored_at, and stored_in.related_to links across system configurations, user profiles, projects, and media pipelines (reducing related_to density by >43%).consolidate_memories from monolithic single-prompt serialization (which previously exceeded CLI subprocess payload and timeout limits on large stores) into category-chunked batches (≤ 25 facts per inference call).trg_memories_trigram_ai/au/ad) to keep the substring trigram virtual table synchronized with memories.memories_trigram maintenance to the routine rebuild_fts workflow in optimize_db.vector_index_jobs, vector_index_state, and vector_index_config (schema version 212).scripts/vector_index_cli.py).memory_worker.py).agy --print) and compact prompt inventory.relates_to to related_to.turn_queue.db.agy --print CLI fallback for tool-free background inference when AGY_MEMORY_INFERENCE_URL is unset, with automatic markdown extraction and slash-command retry.LOCK_SH) allowing seamless cross-user profile inspection between multiple Linux user profiles.AGY_MEMORY_STRICT_GRAPH=false).scripts/auto_sync_hook.py ensuring immediate chat attribution from the very first message.sqlite-vec):
sqlite-vec (C-extension, SIMD-accelerated, zero external daemon).fastembed with paraphrase-multilingual-MiniLM-L12-v2.search_memory.~/.gemini/memory.db.vec_memories, vec_episodes, vec_learnings).scripts/reindex_vectors.py._normalize_category).prune_orphan_links) removing severed graph relationships when entities are deleted or consolidated.optimize_db (compact) CLI command and Web Dashboard /api/optimize endpoint.v2.0 -> v2.1):
agy_memory.py migrate and standalone runner scripts/migrate_v2_to_v2_1.py.~/.gemini/archive/ before applying modifications.hosts -> hosted_on, monitored_by -> monitors).monitoring -> active), topic mapping, and orphan link pruning.PRAGMA user_version = 210.sqlite-vec):
sqlite-vec alongside FTS5.sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2) via fastembed for vague natural language queries.search_memory).memory.db with Hybrid Search on-demand.turn_queue.db.memory_inference.py).agy --print) with markdown JSON extraction and slash-command retry.AGY_MEMORY_STRICT_GRAPH=false) and first-turn Telegram in-flight session resolution.vector_index_jobs) with schema 212 and generational fencing.ux, dev, infra, media).documents, configures, applies_to, resolves, targets, supports) and inverse mappings.claude -p) as alternate background extraction engine.MIT License © 2026 HydStAn
Lightweight SQLite FTS5 dynamic memory layer & MCP server for Google Antigravity (AGY)
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Agy Memory Engine 透過 stdio 在本機執行。
上次檢查時間：2026-10-28。 Lightweight SQLite FTS5 dynamic memory layer & MCP server for Google Antigravity (AGY)
