Language: English | 한국어 | 日本語 | 简体中文 | Español | Français | Deutsch

Geond Agent Protocol

Shared memory and coordination for AI agents that work on the same repo.

Geond gives Copilot Chat, Codex, Claude Code, Antigravity, Manus, CLI agents, and MCP-capable tools a durable place to share what happened, why it happened, what changed, what is reserved, how it was validated, and what the next agent or reviewer should do.

Geond is local-first by default. Your editor, CLI, MCP server, dashboard, and importers can run on your machine against local PostgreSQL. When a team wants multi-machine collaboration, those same local processes can point at a shared PostgreSQL-compatible profile such as Azure Database for PostgreSQL.

Geond is alpha software. Repository-centered memory, MCP, CLI, dashboard read models, reservations, handoffs, code graph indexing, usage evidence, benchmarks, and shared PostgreSQL validation are implemented today. Enterprise IAM, row-level security, dedicated MCP audit streams, broad SaaS adapters, and dependency-expanded automatic reservations are roadmap areas.

About the name: Geond is inspired by an Old English root of "beyond" and is pronounced "Jee-ond". The project helps agents go beyond stateless prompts by connecting them to inspectable shared memory.

Quick Start

Prerequisites: Python 3.11+, uv, Docker with Compose, Git, and ripgrep. See docs/developer_setup.md for OS-specific notes.

cp .env.example .env
uv sync
docker compose up -d postgres
docker compose --profile tools run --rm geond-migrate
uv run geond doctor --format text
uv run geond seed-sample
uv run geond mcp-smoke --format text --strict

Start the MCP server:

uv run geond-mcp

Preview or write MCP client config:

uv run geond install --format text
uv run geond install --write

Serve the read-only dashboard:

uv run geond dashboard serve

Open the printed localhost URL. More MCP client examples are in docs/mcp_client_config.md.

MCP Server And Glama Release

Run the stdio MCP server directly:

uv run geond-mcp

Run it from a Docker image:

docker build -t geond-agent-protocol:local .
docker run --rm -i \
  -e GEOND_DATABASE_URL=postgresql://geond:geond_dev_password@host.docker.internal:55432/geond \
  geond-agent-protocol:local

GEOND_DATABASE_URL points Geond at PostgreSQL. Local development usually uses the Compose database from the quick start. Team mode can use GEOND_DATABASE_PROFILE=azure plus AZURE_GEOND_DATABASE_URL to share memory across machines while keeping each MCP process local.

For registry validation, Glama should deploy this repository's Dockerfile, create a Glama release, and call get_geond_server_info first. That tool does not require a database connection, so it is safe for browser-based smoke tests.

Three representative MCP workflows:

1. Start coordinated work: review_workspace_context -> reserve_files -> edit -> record_changeset.
2. Explain prior context: search_dev_memory -> explain_change -> get_changeset_detail.
3. Leave a handoff: record_agent_action -> record_handoff_summary -> list_handoff_summaries.

What Geond Makes Possible

Demo GIFs

These GIFs are generated from sanitized scenario text, not private transcripts. Regenerate them with uv run python scripts/render_readme_gifs.py.

For browser-verified dashboard captures and longer terminal demo notes, see docs/public_demo_script.md.

Learning Path

Start with learn/README.md for guided notebooks that mirror the README scenarios:

How It Works

flowchart LR
    A[Agent transcripts and actions] --> B[Adapters and redaction]
    B --> P[(PostgreSQL + pgvector)]
    C[MCP clients and CLI] --> M[Geond MCP / CLI]
    M --> P
    P --> S[Search and evidence refs]
    P --> G[Code graph]
    P --> R[Reservations and handoffs]
    P --> D[Read-only dashboard]
    G --> R
    R --> D
    S --> D

1. Memory: importers normalize sessions, events, messages, usage records, and task history from agent tools, then redact common secrets before persistence.
2. Code graph: Python, TypeScript, and JavaScript indexers connect files, symbols, imports, calls, references, and changesets.
3. Reservations: agents can claim files or symbols with TTLs, policy checks, renewals, releases, and auditable reservation events.
4. Handoffs: agents leave structured next-action packets with tested commands, blockers, remaining risks, and evidence refs.
5. Dashboard: humans and PM/orchestrator agents read compact overview, activity, timeline, code risk, usage, lineage, reservations, and handoff read models.
6. Shared PostgreSQL: local-first setups use Docker PostgreSQL; team profiles can point local processes at Azure or another PostgreSQL-compatible backend.

Common Workflows

For a more complete demo path, see docs/demo.md.

Shared Team Database

Use GEOND_DATABASE_URL for the default local database. To keep local processes but share memory across machines, add a second profile: