# Agy Memory Engine > Lightweight SQLite FTS5 dynamic memory layer & MCP server for Google Antigravity (AGY) - **Type:** MCP server - **Install:** `agentstack add mcp-hydstan-agy-memory-engine` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [HydStAn](https://agentstack.voostack.com/s/hydstan) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [HydStAn](https://github.com/HydStAn) - **Source:** https://github.com/HydStAn/agy-memory-engine ## Install ```sh agentstack add mcp-hydstan-agy-memory-engine ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # AGY Memory Engine (v2.4.0) > Hardening branch: see [runtime setup and audit coverage](HARDENING.md). 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. [](https://opensource.org/licenses/MIT) []() > 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 (cooling->past) │ - Decision rationale │ owns, etc.)│ └───────────────────┴────────────────────────────┴────────────────────────────┴───────────────┘ ``` --- ## 🔍 Evolution: From Pure Tokenizer to In-Process Hybrid Search 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: 1. **Ultra-fast CLI Prefetch ("`. - When the user states a new permanent fact or personal rule, persist it using `store_memory` or `record_learning`. ``` #### Option C: Autonomous Background Sync (Zero-friction) To have the memory engine automatically learn from your conversations without you lifting a finger: 1. Register the turn hook in `~/.gemini/config/hooks.json` (see [Autonomous Background Pipeline](#-autonomous-background-pipeline-cron--lifecycle-hooks)). 2. Add the debounced background worker to your crontab (`*/5 * * * * python3 /path/to/agy-memory-engine/memory_worker.py`). --- ## 🚀 CLI Reference & Quick Commands ```bash # Multi-Layer Prefetch ( scripts/auto_sync_hook.py) │ (Enqueues turn in ` to the URL on your first visit: ```text http://localhost:8085/?token=your_secure_dashboard_token_here # Or over Tailscale: https://.ts.net:8085/?token=your_secure_dashboard_token_here ``` The token is saved in browser `localStorage`, so subsequent reloads and visits do not require re-entering it. 4. **API Requests**: Pass the header `Authorization: Bearer `. ### Starting the Dashboard ```bash # 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 ``` --- ## ⏰ Autonomous Background Pipeline (Cron & Lifecycle Hooks) To enable 100% autonomous background learning without manual intervention, configure the **AGY Lifecycle Hook** and the **Linux Crontab**: ### 1. Global Lifecycle Hook (`~/.gemini/config/hooks.json`) Registers the transcript collector on every agent turn stop: ```json { "memory-auto-sync": { "enabled": true, "Stop": [ { "type": "command", "command": "python3 /opt/agy-memory-engine/scripts/auto_sync_hook.py", "timeout": 15 } ] } } ``` ### 2. Crontab Configuration (`crontab -e`) ```bash # 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 ``` --- ## 🧪 Testing ```bash python3 -m unittest discover tests/ -v # Ran 229 tests (OK) ``` --- ## 🚀 Release Notes ### v2.4.0 (2026-09-21) - **Vector Index Synchronization & Outbox Architecture**: - Self-healing vector synchronization with `vector_index_jobs`, `vector_index_state`, and `vector_index_config` (schema version 212). - Decoupled embedding computation from SQLite write transactions; atomic revision tracking and job enqueueing via database triggers. - Generational fencing, revision fencing, and lease tracking preventing race conditions during background vector draining. - Dedicated CLI inspection & draining tool (`scripts/vector_index_cli.py`). - **Interactive Knowledge Graph & Dashboard Enhancements**: - Interactive vis.js network graph visualization for exploring Layer 4 relational entity links directly in the Web Dashboard. - Cluster domain filtering and relationship-type pruning for dense graph navigation. - Live engine status indicators in the dashboard header: Git commit SHA, commit message, and one-click engine restart. - Optional semantic LLM consolidation checkbox in the optimization modal. - **Queue Reliability & Inference Hardening**: - Turn size capping at enqueue time to prevent poisoned oversized claim batches. - Adaptive batch splitting on retries instead of replaying failed batches whole. - Configurable queue batch sizing and increased per-run worker caps (`memory_worker.py`). - Streamed JSON input/output for CLI inference (`agy --print`) and compact prompt inventory. - **Taxonomy & Graph Normalization**: - Canonical mapping of `relates_to` to `related_to`. - **Jev Relevance Gate (Post-v2.4.0 / PR #3)**: - Evaluation-model candidate filtering dropping irrelevant retrieval results before context injection, with full fail-open behavior. ### v2.3.0 (2026-09-14) - **Comprehensive Hardening, WAL-Safe Storage & Queue Reliability**: - Atomic batch claims with durable batch receipts and recoverable expiring leases in `turn_queue.db`. - Concurrency hardening: serialized schema bootstrap, entity revision tracking, and generation fencing preventing stale overwrites across restores. - Native `agy --print` CLI fallback for tool-free background inference when `AGY_MEMORY_INFERENCE_URL` is unset, with automatic markdown extraction and slash-command retry. - Multi-user dashboard and permission resilience: shared maintenance lock (`LOCK_SH`) allowing seamless cross-user profile inspection between multiple Linux user profiles. - Tolerant entity graph linking: invalid or unresolvable relationship endpoints are skipped with warnings instead of rolling back the entire extraction transaction (`AGY_MEMORY_STRICT_GRAPH=false`). - First-turn Telegram routing: in-flight session resolution in `scripts/auto_sync_hook.py` ensuring immediate chat attribution from the very first message. - Bounded MCP maintenance offloading to a single background worker thread to keep the event loop responsive. ### v2.2.0 (2026-09-07) - **Semantic Recall & In-Process Hybrid Search (FTS5 + `sqlite-vec`)**: - In-process vector extension via `sqlite-vec` (C-extension, SIMD-accelerated, zero external daemon). - Dense 384-dimensional multilingual embeddings via `fastembed` with `paraphrase-multilingual-MiniLM-L12-v2`. - Reciprocal Rank Fusion (RRF) combining BM25 lexical precision with semantic cosine similarity in `search_memory`. - Zero latency impact on CLI prefetch: Pre-invocation prefetch remains strictly v2.1`)**: - Dedicated CLI migration command `agy_memory.py migrate` and standalone runner `scripts/migrate_v2_to_v2_1.py`. - Automatic safety snapshot backups in `~/.gemini/archive/` before applying modifications. - Semantic relation remapping and directional inversion (e.g. `hosts` -> `hosted_on`, `monitored_by` -> `monitors`). - Strict episode status normalization (`monitoring` -> `active`), topic mapping, and orphan link pruning. - FTS5 virtual table rebuilds and database vacuuming with `PRAGMA user_version = 210`. --- ## 🗺️ Roadmap - [x] **Semantic Recall & Hybrid Search (FTS5 + `sqlite-vec`)**: - In-process vector extension via `sqlite-vec` alongside FTS5. - Multilingual embedding model (`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`) via `fastembed` for vague natural language queries. - Reciprocal Rank Fusion (RRF) to combine BM25 keyword precision with semantic vector similarity for on-demand queries (`search_memory`). - Keep pre-invocation prefetch strictly < 2ms (FTS5 + Trigram). - [x] **Hermes-Style 3-Tier Memory Architecture**: - **Tier 1 (Profile/Preferences)**: Lean, fixed identity facts injected directly into agent system prompt (0ms latency, ~150-250 tokens max). - **Tier 2 (Episodic & Semantic Store)**: 4-Layer SQLite `memory.db` with Hybrid Search on-demand. - **Tier 3 (Working Memory)**: Active session context & scratchpad. - [x] **Production Hardening, WAL Concurrency & Tool-Free Inference (v2.3.0)**: - Atomic batch claims, durable batch receipts, and recoverable expiring worker leases in `turn_queue.db`. - Concurrency hardening: serialized schema bootstrap, entity revision tracking, and generation fencing. - Tool-free Direct Provider API: Native lightweight connector for OpenAI-compatible endpoints without external CLI dependencies (`memory_inference.py`). - Native Antigravity CLI fallback (`agy --print`) with markdown JSON extraction and slash-command retry. - Multi-user dashboard resilience and cross-user maintenance locking. - Tolerant graph linking (`AGY_MEMORY_STRICT_GRAPH=false`) and first-turn Telegram in-flight session resolution. - [x] **Vector Index Synchronization & Interactive Knowledge Graph (v2.4.0)**: - Asynchronous, self-healing vector index outbox (`vector_index_jobs`) with schema 212 and generational fencing. - Interactive vis.js graph visualization in Web Dashboard with domain filtering and physics layout. - Turn size capping, retry batch-splitting, and streaming CLI inference. - Jev candidate relevance gating for clean retrieval contexts. - [ ] **Extended Agent & CLI Integrations**: - **Claude Code Compatibility**: Support Claude CLI (`claude -p`) as alternate background extraction engine. - Dynamic extraction profile tagging per client/agent session (multi-agent orchestration). - [ ] **Selective Synced Subgraphs**: - Export and sync filtered memory subsets across distributed nodes over Tailscale mesh. --- ## 📄 License MIT License © 2026 HydStAn ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [HydStAn](https://github.com/HydStAn) - **Source:** [HydStAn/agy-memory-engine](https://github.com/HydStAn/agy-memory-engine) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-hydstan-agy-memory-engine - Seller: https://agentstack.voostack.com/s/hydstan - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.