⚡ 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, column-weighted BM25 ranking (title: 10x, concepts: 5x, facts: 3x), and automatic prefix fuzzy matching (term*).
2. Auto-Project Scoping: Automatically senses your active CWD or Git repository to prioritize and scope memories without manual flags, with automatic global fallback.
3. 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.
4. Official MCP Server: Speaks standard Model Context Protocol (JSON-RPC 2.0 stdio), exposing search, recall, get_observations, timeline, and sync.
5. Sub-50ms Latency: Instant terminal search and prompt recall.

📊 Comparison

🚀 Installation

Option 1: Via pip (Standard Python Package)

pip install agy-mem
agy-mem init

(Running agy-mem init registers the MCP server in ~/.gemini/config/mcp_config.json, generates schemas, and configures /recall and /mem slash commands).

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 (auto-scoped to current repo, or global)
agy-mem search "statusl"               # Prefix match e.g. statusline
agy-mem search "offline prayer"        # Auto-scoped to current project (e.g. Aya)
agy-mem search "offline prayer" -a     # -a / --all searches across all projects

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

# View chronological timeline (auto-scoped to current repo, or global with -a)
agy-mem timeline --limit 5
agy-mem timeline -a --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.