Agy Memory Engine

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

# 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:

{
  "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)

# 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

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
• Source: HydStAn/agy-memory-engine
• License: MIT

Install and usage instructions live in the source repository linked above.