Agent Bridge & Shared MemSearch Suite

Unified configuration, skill/MCP routing, and MemSearch persistent memory bridge across Claude Code (claude), OpenAI Codex CLI (codex), and Google Antigravity (agy).

---

Architecture

Configuration bridge

bridge.py status audits all three agents; sync previews changes and sync --apply writes them. Each configuration type has its own sync direction:

flowchart TB
    B["bridge.py<br/>Audit · Preview · Apply"]
    B --> R["Rules<br/>AGENTS.md → CLAUDE.md"]
    B --> S["Skills<br/>Shared links + AGY manifest"]
    B --> M["MCP servers<br/>Codex → AGY by default"]
    B --> H["Hooks<br/>Register AGY lifecycle adapter"]

    classDef bridge fill:#eef2ff,stroke:#6366f1,color:#312e81
    classDef config fill:#f8fafc,stroke:#94a3b8,color:#0f172a
    class B bridge
    class R,S,M,H config

Loading

Shared memory flow

Agents working in the same project share Markdown memory and a project-scoped search collection. The hooks capture turns; agents use memory-recall to retrieve relevant history when needed.

flowchart TB
    subgraph Entry["Agent integration"]
        CC["Claude Code"] --> UP["Upstream MemSearch plugin"]
        CX["Codex CLI"] --> RT["Codex hook runtime"]
        AG["Antigravity · AGY"] --> AD["AGY adapter<br/>Events + transcripts"]
        AD -->|reuse| RT
    end

    subgraph Store["Shared project memory · .memsearch/"]
        MD["Markdown journals<br/>Source of truth"]
        IX[("Milvus index<br/>Project collection")]
        MD -->|index| IX
    end

    UP -->|capture| MD
    RT -->|capture| MD
    IX --> Q["Recall on demand<br/>memory-recall: search / expand"]

    MD -.->|periodic| CL["cleanup/<br/>Weekly digests + archived originals"]
    CL -->|index digests| IX

    classDef agent fill:#eef2ff,stroke:#6366f1,color:#312e81
    classDef runtime fill:#f8fafc,stroke:#94a3b8,color:#0f172a
    classDef memory fill:#ecfdf5,stroke:#10b981,color:#064e3b
    classDef maintenance fill:#fffbeb,stroke:#d97706,color:#78350f
    class CC,CX,AG agent
    class UP,RT,AD runtime
    class MD,IX,Q memory
    class CL maintenance

Loading

Solid arrows show runtime calls or data flow; the dashed arrow shows periodic maintenance. Session start also injects a recent-memory preview. Local helpers handle process cleanup and update notices; verify.py validates the setup offline. See the hook mapping for lifecycle details.

---

What It Solves

Official MemSearch ships plugins for Claude Code and Codex CLI, but:

1. No official Antigravity (agy) adapter: AGY uses a distinct hooks.json schema ({"memsearch": {"SessionStart": [...], "PreInvocation": [...], "Stop": [...]}}), camelCase protojson payloads (workspacePaths, conversationId, transcriptPath, lastUserInput wrapped in <USER_REQUEST>), injectSteps output contracts, and USER_INPUT / PLANNER_RESPONSE transcript JSONL records.
2. Duplicate skill & config drift across 3 agents:
   • Codex scans both ~/.agents/skills and ~/.codex/skills, whereas Antigravity scans ~/.agents/skills (plus .agents/skills.json manifests), and Claude Code scans ~/.claude/skills (plus marketplace plugins). Naively copying or symlinking all skills into every folder causes duplicate skill warnings in Codex and Claude Code.
   • CLAUDE.md and AGENTS.md routing rules, as well as MCP server definitions (~/.claude.json, ~/.codex/config.toml, ~/.gemini/config/mcp_config.json), easily drift out of sync.
3. Long-term memory hygiene & safe process cleanup:
   • Daily raw/summarized logs in .memsearch/memory/YYYY-MM-DD.md grow unbounded without periodic distillation and archival (cleanup/).
   • Orphaned background memsearch watch / memsearch index processes require PID-verified (pidfd) cleanup on session exit (local-hooks/session-end.py) without killing unrelated Milvus instances.

---

Directory Layout

Path	Purpose
bridge.py	Zero-dependency Python 3.10+ CLI to audit (status) and synchronize (sync) Rules, Skills, MCP servers, and Hooks across Claude Code, Codex, and Antigravity.
antigravity-plugin/hooks.py	Antigravity (agy) lifecycle hook adapter (SessionStart, turn-deduplicated PreInvocation, and Stop transcript parser).
codex-plugin/	Stable-path MemSearch hook runtime (session-start.sh, user-prompt-submit.sh, stop.sh, common.sh, derive-collection.sh) with zero-model-call raw capture support when plugins.codex.summarize.enabled = false.
local-hooks/session-end.py	Linux/WSL pidfd-verified SessionEnd cleanup hook that terminates only recorded memsearch watch/index processes for the current project.
local-hooks/update_notice.py	Non-blocking background CI status checker for the tracked MemSearch fork across codex, claude, and agy.
local-hooks/verify.py	10-group offline verification suite (verify-memsearch) testing configuration, timeouts, syntax, Codex/Claude/AGY capture, process scope isolation, exit cleanup, and the 3-way bridge.
cleanup/	7-day gated memory maintenance (run-if-due.sh → cleanup.sh → distill.py): distills logs older than 14 days into weekly digests (memory/digest/) and moves raw logs to .memsearch/archive/.

---

Three-Platform Hook Mapping

Lifecycle Phase	Claude Code (~/.claude/settings.json)	Codex CLI (~/.codex/hooks.json)	Antigravity (~/.agents/hooks.json)
Session Start	SessionStart (memsearch plugin + update_notice.py claude)	SessionStart (session-start.sh + run-if-due.sh + update_notice.py codex)	SessionStart (antigravity-plugin/hooks.py SessionStart → status + recall context + run-if-due.sh + update_notice.py agy)
Prompt / Turn Start	UserPromptSubmit (memsearch plugin + update_notice.py claude)	UserPromptSubmit (user-prompt-submit.sh + update_notice.py codex)	PreInvocation (antigravity-plugin/hooks.py PreInvocation with per-turn (conversationId, lastUserInput) SHA-256 deduplication)
Turn Stop (Capture)	Stop (async Haiku summary)	Stop (stop.sh detached worker)	Stop (antigravity-plugin/hooks.py Stop → parses AGY transcript_full.jsonl → stop.sh --worker)
Session End	SessionEnd	SessionEnd (local-hooks/session-end.py)	Handled via orphan PID cleanup on next SessionStart

---

Usage

1. Audit 3-Way Status

python3 ~/.local/share/memsearch/bridge.py status
# Or machine-readable JSON (with automatic secret redaction):
python3 ~/.local/share/memsearch/bridge.py status --json

2. Synchronize Rules, Skills, MCP Servers, and Hooks

# Preview planned changes (dry-run):
python3 ~/.local/share/memsearch/bridge.py sync

# Apply synchronization across Claude Code, Codex, and Antigravity:
python3 ~/.local/share/memsearch/bridge.py sync --apply

3. Run the 10-Group Offline Verification Suite

python3 ~/.local/share/memsearch/local-hooks/verify.py

All tests run in isolated temporary directories with simulated model/CLI stubs and never touch live Milvus databases or external APIs.

---

Antigravity (agy) Configuration Reference

1. Lifecycle Hooks (~/.agents/hooks.json)

SessionStart shares a 27-second internal budget across project lookup and all subhooks, leaving headroom under AGY's 30-second timeout. Each subhook is capped by the remaining budget; when it expires, later steps are skipped and any memory context already loaded is returned.

{
  "memsearch": {
    "SessionStart": [
      {
        "type": "command",
        "command": "python3 ~/.local/share/memsearch/antigravity-plugin/hooks.py SessionStart",
        "timeout": 30
      }
    ],
    "PreInvocation": [
      {
        "type": "command",
        "command": "python3 ~/.local/share/memsearch/antigravity-plugin/hooks.py PreInvocation",
        "timeout": 10
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "python3 ~/.local/share/memsearch/antigravity-plugin/hooks.py Stop",
        "timeout": 30
      }
    ]
  }
}

2. Cross-Agent Skill Discovery (~/.agents/skills.json)

Mounts ~/.codex/skills into Antigravity without creating duplicate directories inside ~/.agents/skills/ (which Codex would otherwise load twice):

{
  "entries": [
    {
      "path": "~/.codex/skills",
      "exclude": ["\\.system", "gscloud-api"]
    }
  ]
}

---

Acknowledgements & Upstream Notice

This project builds upon MemSearch (zilliztech/memsearch) by Zilliz. Full credit goes to the MemSearch authors and maintainers for the underlying Markdown-first + Milvus/ONNX hybrid memory engine, CLI, and baseline Codex/Claude Code plugin scripts included under codex-plugin/ and _shared/.

Note to Upstream Maintainers (zilliztech/memsearch):

• If the upstream MemSearch team prefers that these bundled runtime scripts and multi-agent extensions not be hosted as a standalone public repository, I am happy to take down or archive this repository immediately upon request — provided that the Google Antigravity (agy) plugin/hook integration and cross-agent bridge improvements are merged into upstream zilliztech/memsearch with collaborator access / credit granted.
• 致上游 zilliztech/memsearch 维护团队：本项目基于官方 MemSearch 构建并扩展了 Google Antigravity (agy) 生命周期钩子适配层与 Claude Code / Codex / AGY 三端配置同步桥接。若上游团队不希望本仓库单独公开托管，只需将 Antigravity (agy) 适配配置并入官方仓库并授予项目 Collaborator 权限，本人愿意随时配合下架本独立仓库。