⚡ The Problem & The Solution

When working with AI coding agents like Google Antigravity (agy), starting a new session often means starting with amnesia. You find yourself repeatedly explaining project architectures, database schemas, prior bugfixes, and coding preferences.

Tools like claude-mem and antigravity-memory attempt to solve this, but require heavy Node.js runtimes, hundreds of megabytes of node_modules, and external API keys to pay for AI summarizations.

agy-mem solves this natively:

1. 0 Dependencies: Pure Python 3 standard library with native SQLite FTS5 and BM25 ranking.
2. Native Trajectory Observer: Reads directly from Antigravity's internal brain/*/transcript.jsonl and conversation databases. It extracts tools called, exact files modified, and assistant outcomes without burning API tokens.
3. Official MCP Server: Speaks standard Model Context Protocol (JSON-RPC 2.0 stdio), exposing search, recall, get_observations, timeline, and sync.
4. Sub-50ms Latency: Instant terminal search and prompt recall.

📊 Comparison

🚀 Installation

Option 1: Via pip (Standard Python Package)

pip install agy-mem

Option 2: 1-Line Automated Setup (Includes MCP & Antigravity Skills)

Install agy-mem, register the MCP server, and add the /recall & /mem slash commands in a single command:

curl -sSL https://raw.githubusercontent.com/Cancelllls/agy-mem/main/install.sh | bash

Option 3: Clone & Install Manually

git clone https://github.com/Cancelllls/agy-mem.git
cd agy-mem
chmod +x install.sh
./install.sh

💡 How to Use

1. In Any Terminal

# Search memories with high-visibility formatted cards
agy-mem search "fiqh zakat"
agy-mem search "statusline timeout" -p Antigravity

# Recall context formatted for prompt injection
agy-mem recall "offline barcode scanner"

# View chronological timeline (latest first, or origin first)
agy-mem timeline --limit 5
agy-mem timeline --earliest --limit 3

# Check database health & breakdown by project
agy-mem status

# Manually store a technical observation
agy-mem add --project Aya --type architecture --title "WAL Mode SQLite" --narrative "Enabled WAL mode and memory pragmas."

# Trigger incremental sync of newly completed turns
agy-mem sync

2. Inside Google Antigravity (agy prompt)

agy-mem installs native slash commands in ~/.agent/skills/:

• /recall <topic>: Injects past decisions, bugfixes, and code files directly into your active prompt context.
• /mem: Displays the live memory dashboard, synced session counts, and database health.

3. As an MCP Server (Model Context Protocol)

agy-mem automatically registers itself in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "agy-mem": {
      "command": "/home/ubuntu/.local/bin/agy-mem",
      "args": ["mcp"]
    }
  }
}

Any MCP-compatible AI agent can now call:

• search: Full-text memory search with BM25 scoring.
• get_observations: Fetch complete details and diffs for observation IDs.
• recall: Markdown context block formatted for immediate reasoning.
• timeline: Chronological event sequence.
• add_observation: Store new decisions programmatically.
• sync: Trigger background observation extraction.

🏗️ Architecture

flowchart TD
    subgraph Antigravity ["Google Antigravity Runtime"]
        B["brain/*/transcript.jsonl"]
        C["conversations/*.db"]
    end

    subgraph agyMem ["agy-mem Engine"]
        Obs["Trajectory Observer & Turn Parser"]
        FTS["SQLite FTS5 Engine\n(~/.gemini/antigravity-cli/memory.db)"]
        BM["BM25 Ranking & Indexer"]
    end

    subgraph Interfaces ["Access Interfaces"]
        CLI["CLI: agy-mem search / timeline"]
        Slash["Slash Commands: /recall, /mem"]
        MCP["MCP Server: stdio JSON-RPC"]
    end

    B --> Obs
    C --> Obs
    Obs --> FTS
    FTS --> BM
    BM --> CLI
    BM --> Slash
    BM --> MCP

📄 License

MIT License © 2026 Abdalrahman Samir / Cancellls. See LICENSE for details.