The Geond Agent Protocol server provides shared memory and coordination infrastructure for AI agents working on the same code repository, enabling them to share context, avoid conflicts, and hand off work seamlessly.
Server & Discovery
Get a read-only summary of the server's purpose, tools, and setup hints (no database connection required)
Memory & Search
Search agent transcripts, changesets, and development memory using keyword, vector, or hybrid retrieval
Explain why a file changed using stored changesets, code graph entries, and related messages
Retrieve full changeset details by UUID, git SHA, or SHA prefix
Look up code graph entities matching a symbol name (functions, classes, methods)
Recording & Code Graph
Persist code changesets with files, patches, git metadata, and session links
Log agent actions so other agents can see active intent and progress
Import language-server reference edges into the code graph
Workspace Management
Register/list workspace aliases for moved or renamed repositories
Record and match repository fingerprints for alias detection
Get/set coordination policies (advisory, strict, override) for parallel editing
File & Symbol Reservations
Reserve, release, and renew file reservations with TTL and conflict detection
Reserve, release, and renew symbol reservations for finer-grained coordination
View active file reservations and symbol conflicts
Handoffs
Record structured handoff summaries with next steps, blockers, and risks
List and close handoff summaries for task transfer between agents or humans
Audit, Context & Dashboard
Inspect reservation lifecycle audit events
Review workspace context (reservations, handoffs, lineage) before starting work
Get workspace lineage graphs showing sessions, changesets, and handoffs
Retrieve normalized agent activity events for dashboards and orchestrators
Get a compact dashboard overview summarizing current state, recent activity, and risks
Language: English | 한국어 | 日本語 | 简体中文 | Español | Français | Deutsch
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.
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 --strictStart the MCP server:
uv run geond-mcpPreview or write MCP client config:
uv run geond install --format text
uv run geond install --writeServe the read-only dashboard:
uv run geond dashboard serveOpen the printed localhost URL. More MCP client examples are in docs/mcp_client_config.md.
Related MCP server: Cerefox
Run the stdio MCP server directly:
uv run geond-mcpRun 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:localGEOND_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:
Start coordinated work: review_workspace_context -> reserve_files -> edit -> record_changeset.
Explain prior context: search_dev_memory -> explain_change -> get_changeset_detail.
Leave a handoff: record_agent_action -> record_handoff_summary -> list_handoff_summaries.
Scenario | What you can do | Proof and entrypoint |
AI pair coding across agent tools | Let different agents work on the same repo through shared memory, reservations, handoffs, and review context. Verified locally with Codex and Antigravity; the same pattern applies to Copilot, Claude Code, Continue, Manus, or custom MCP agents. | docs/antigravity_codex_geond_verification.md, docs/mcp_client_config.md |
Multi-PC collaboration | Run | docs/azure_validation/team_collab_validation.md, docs/azure_validation/README.md |
PM and reviewer dashboard | Review agent lanes, sessions, handoffs, changesets, code risk, usage evidence, timeline, and lineage without reading raw MCP JSON. |
|
Safe parallel editing | Ask agents to review current context, reserve files or symbols, record changesets, and leave structured handoffs before another agent edits the same target. | docs/agent_operating_loop.md, |
Cross-agent memory import | Import Copilot Chat, Codex, Claude Code, Antigravity, and Manus task evidence into one redacted search and evidence model. | |
Compact MCP context | Return snippets, evidence refs, scores, and follow-up detail paths instead of flooding an LLM with raw transcripts by default. | tests/test_mcp_payload_budget.py, docs/ai_usage_observability.md |
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.
Start with learn/README.md for guided notebooks that mirror the README scenarios:
Lesson | Focus |
Run local PostgreSQL, seed sample evidence, search memory, and smoke-test MCP. | |
Practice context review, symbol reservations, conflicts, and handoff packets. | |
Share evidence between Agent A and Agent B across different agent tools. | |
Understand optional shared PostgreSQL profiles for multi-PC collaboration. |
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 --> DMemory: importers normalize sessions, events, messages, usage records, and task history from agent tools, then redact common secrets before persistence.
Code graph: Python, TypeScript, and JavaScript indexers connect files, symbols, imports, calls, references, and changesets.
Reservations: agents can claim files or symbols with TTLs, policy checks, renewals, releases, and auditable reservation events.
Handoffs: agents leave structured next-action packets with tested commands, blockers, remaining risks, and evidence refs.
Dashboard: humans and PM/orchestrator agents read compact overview, activity, timeline, code risk, usage, lineage, reservations, and handoff read models.
Shared PostgreSQL: local-first setups use Docker PostgreSQL; team profiles can point local processes at Azure or another PostgreSQL-compatible backend.
Goal | Command or doc |
Check environment |
|
Import Copilot Chat |
|
Import Codex |
|
Import Claude Code |
|
Import Antigravity |
|
Import Manus task |
|
Search memory |
|
Index code |
|
Record a changeset |
|
Reserve work |
|
Review conflicts |
|
Leave handoff |
|
Check orchestrator run |
|
Agent operating loop | |
MCP clients |
For a more complete demo path, see docs/demo.md.
Use GEOND_DATABASE_URL for the default local database. To keep local processes
but share memory across machines, add a second profile:
GEOND_DATABASE_PROFILE=azure
AZURE_GEOND_DATABASE_URL=postgresql://...The dashboard classifies the active source as local PostgreSQL, Azure PostgreSQL, or remote PostgreSQL without showing user info, passwords, or tokens. The validated team flow is documented in docs/azure_validation/team_collab_validation.md.
Geond's README borrows a few public onboarding patterns and adapts them to this project rather than copying their product scope:
OpenHuman: explain transparent, local-first memory and compact context clearly.
CLI-Anything: make the first screen visual and action-oriented with short commands and GIFs.
Microsoft AI Agents for Beginners: present agent concepts as scenario tables and repeatable learning paths.
docs/architecture.md explains the system layers and data model.
docs/agent_activity_dashboard.md describes dashboard read models and PM/orchestrator views.
docs/agent_operating_loop.md defines the read, reserve, record, and handoff loop for agents.
docs/agent_testbeds.md tracks Copilot Chat, Codex, Claude Code, and Antigravity test beds.
docs/manus_integration.md documents Manus API v2 import, context packets, task contracts, and limitations.
docs/mcp_client_config.md shows VS Code, Claude Desktop, Continue, Antigravity, and other MCP client setup.
docs/ai_usage_observability.md covers token, cost, pricing snapshot, and usage-versus-evidence design.
docs/benchmarking.md explains retrieval, evidence, and agent-run benchmark commands.
docs/open_source_readiness.md tracks launch risks, privacy, dependency, and governance issues.
learn/README.md provides a notebook-based onboarding path.
Contributions are welcome while the project is alpha. Good first areas are importers, docs, tests, dashboard read-model improvements, MCP contract tests, installer ergonomics, and focused adapters for non-development work artifacts.
Read CONTRIBUTING.md before opening a PR. It covers setup, privacy rules, test commands, redaction expectations, and files that must stay out of git. Security reporting is in SECURITY.md.
Geond is designed for local-first use. Importers redact common secrets before
persistence, external embeddings are opt-in, and the dashboard avoids exposing
credential-bearing connection strings. Even so, agent transcripts can contain
sensitive information. Review .env, transcripts, screenshots, benchmark logs,
and dashboard captures before sharing them.
Do not commit private transcripts, local evidence exports, local-only drafts,
repo, tmp, result, results, or generated videos. See
SECURITY.md and docs/open_source_readiness.md.
Apache-2.0. See LICENSE.
Purpose: Mark a handoff as consumed or no longer active. When to use: call after the receiving agent has acted on the handoff or a human has reviewed it. Inputs: handoff_id and final status. Side effects: updates handoff status. Output: count of closed records. Failure modes: returns zero when the handoff id does not match an active row.
Inputs: handoff_id (required), status. Returns: object
Purpose: Explain why a file may have changed using stored changesets, code graph entries, snapshots, and related messages. When to use: call during code review, bug triage, or handoff recovery when a file path needs historical context. Inputs: file_path identifies the repo-relative file; limit caps evidence volume; include_narrative adds a deterministic cited summary. Side effects: none beyond database reads. Output: changesets, touched entities, snapshots, related messages, and optional geond.evidence.v1 narrative citations. Failure modes: returns sparse evidence when the file was not indexed or imported.
Inputs: file_path (required), limit, include_narrative. Returns: object
Purpose: Read current file reservations for a workspace. When to use: call before editing or reviewing files to detect coordination conflicts. Inputs: workspace_id and optional file_paths filter. Side effects: none beyond database reads. Output: active reservations with agents, purpose, TTL, and file paths. Failure modes: returns an empty list when no active reservations match.
Inputs: workspace_id (required), file_paths. Returns: result
Purpose: Return normalized activity events for dashboards and orchestrators. When to use: call to inspect recent agent runs, reservations, handoffs, changesets, or status transitions. Inputs: workspace_id plus optional limit, kind, agent, and status filters. Side effects: none beyond database reads. Output: event records normalized for UI or agent consumption. Failure modes: returns an empty event list when no activity matches.
Inputs: workspace_id (required), kind, agent, limit, +1 more. Returns: object
Purpose: Retrieve full stored detail for one changeset. When to use: call after a search or file explanation returns a changeset id or git commit that needs closer inspection. Inputs: changeset_ref accepts a UUID, full git SHA, or unambiguous SHA prefix; include_narrative controls cited prose. Side effects: none beyond database reads. Output: files, touched code entities, evidence references, ambiguity status, and optional narrative. Failure modes: returns found=false for missing refs or ambiguous=true when a prefix matches multiple changesets.
Inputs: changeset_ref (required), include_narrative. Returns: object
Purpose: Return a compact read-only dashboard summary for one workspace. When to use: call when a human reviewer, PM agent, or orchestrator needs current state without reading raw transcripts. Inputs: workspace_id and limit. Side effects: none beyond database reads. Output: summary cards, recent activity, handoffs, reservations, and risk signals. Failure modes: returns sparse sections for a new workspace.
Inputs: workspace_id (required), limit. Returns: object
Purpose: Return a safe, read-only summary of the Geond Agent Protocol MCP server. When to use: Call this first when an MCP host, Glama browser session, or new agent needs to understand what Geond does before connecting it to PostgreSQL. Inputs: none. Side effects: none; this tool never opens a database connection and does not read local transcripts. Output: server purpose, version, environment variables, tool groups, setup hints, and example workflows. Failure modes: only package metadata lookup fallback is expected, in which case the declared alpha version is returned.
Inputs: no named parameters. Returns: object
Purpose: Read active symbol reservations that could conflict with planned work. When to use: call before changing shared APIs or named entities. Inputs: workspace_id and optional symbols filter. Side effects: none beyond database reads. Output: active symbol reservations with owners, purposes, and expiry. Failure modes: returns an empty list when there are no active conflicts.
Inputs: workspace_id (required), symbols. Returns: result
Purpose: Find known code graph entities that match a symbol name. When to use: call before modifying a function, class, method, or variable so the agent can see definitions and related changesets. Inputs: symbol is the name to match; limit caps returned entities. Side effects: none beyond database reads. Output: matching entities with file locations, workspace data, related changesets, and evidence refs. Failure modes: returns an empty list when the code graph has not indexed the symbol.
Inputs: symbol (required), limit. Returns: result
Purpose: Read reservation and conflict policy for a workspace. When to use: call before reserving files or symbols in a multi-agent workflow. Inputs: workspace_id_or_uri identifies the workspace. Side effects: none beyond database reads. Output: current conflict policy and related coordination settings. Failure modes: fails when the workspace cannot be resolved.
Inputs: workspace_id_or_uri (required). Returns: object
Purpose: Return a graph of major collaboration artifacts for a workspace. When to use: call when an agent needs a high-level map of sessions, changesets, handoffs, reservations, and activity. Inputs: workspace_id and limit. Side effects: none beyond database reads. Output: nodes and edges suitable for dashboard or orchestration analysis. Failure modes: returns a sparse graph for new or unindexed workspaces.
Inputs: workspace_id (required), limit. Returns: object
Purpose: Retrieve handoff packets for a workspace or across workspaces. When to use: call when resuming a task, auditing pending work, or preparing context for another agent. Inputs: optional workspace filter, status filter, and limit. Side effects: none beyond database reads. Output: handoff summaries with status, agents, next steps, blockers, and risks. Failure modes: returns an empty list when no handoffs match.
Inputs: limit, status, workspace_id_or_uri. Returns: result
Purpose: Inspect audit history for reservation lifecycle events. When to use: call during conflict analysis, stale reservation cleanup, or team coordination review. Inputs: optional workspace, reservation kind, action filter, and limit. Side effects: none beyond database reads. Output: created, renewed, released, and expired reservation events. Failure modes: returns an empty list when no events match.
Inputs: limit, action, reservation_kind, workspace_id_or_uri. Returns: result
Purpose: Inspect workspace alias mappings. When to use: call when an agent is unsure whether two filesystem roots point to the same repository memory. Inputs: workspace_id_or_uri optionally scopes the list. Side effects: none beyond database reads. Output: alias rows including canonical workspace identifiers and reasons. Failure modes: returns an empty list when no aliases exist or the filter matches nothing.
Inputs: workspace_id_or_uri. Returns: result
Purpose: Log what an agent is doing in a workspace. When to use: call at the start or end of meaningful work so other agents can see active intent and progress. Inputs: workspace_id, agent_name, action_type, summary, optional intent/status/session ids. Side effects: writes an activity row. Output: action_id for future references. Failure modes: fails when the workspace id is invalid.
Inputs: summary (required), agent_name (required), action_type (required), workspace_id (required), +4 more. Returns: object
Purpose: Persist a code changeset with files, optional patches, git metadata, and session links. When to use: call after an agent edits or reviews files so future agents can understand what changed and why. Inputs: files contains changed file objects; workspace_id or workspace_uri is required; metadata links commits, branches, intent, and sessions. Side effects: writes changeset and file rows. Output: changeset identifiers and summary fields. Failure modes: raises when no workspace identifier is supplied or payloads are invalid.
Inputs: files (required), branch, intent, summary, +7 more. Returns: object
Purpose: Store a structured handoff packet for the next agent or human reviewer. When to use: call when pausing, finishing, or transferring a task. Inputs: workspace_id, from/to agents, summary, next steps, blockers, tested commands, remaining risks, next action, and template. Side effects: writes a handoff row. Output: handoff_id for future retrieval. Failure modes: invalid workspace or malformed list fields are rejected.
Inputs: summary (required), workspace_id (required), from_agent_name (required), status, +7 more. Returns: object
Purpose: Import language-server reference edges into the code graph. When to use: call after collecting definitions or references from an external LSP client. Inputs: workspace_id, reference payloads, and replace flag. Side effects: writes or replaces code graph reference rows. Output: import counts and status. Failure modes: malformed reference payloads or invalid workspace ids are rejected.
Inputs: references (required), workspace_id (required), replace. Returns: object
Purpose: Store durable repository identity fingerprints for alias detection. When to use: call after discovering git remotes, first commits, or other stable repo identifiers on a workspace. Inputs: workspace_id_or_uri selects the workspace; fingerprints is a list of typed identity facts. Side effects: writes fingerprint rows. Output: stored fingerprint records. Failure modes: fails when the workspace cannot be resolved or fingerprint payloads are malformed.
Inputs: fingerprints (required), workspace_id_or_uri (required). Returns: result
Purpose: Link a moved or renamed workspace URI to an existing workspace record. When to use: call when the same repository appears under a new local path, mount point, or machine-specific URI. Inputs: workspace_id_or_uri selects the existing workspace; alias_uri is the new URI; reason and metadata document why it changed. Side effects: writes an alias row. Output: alias record details. Failure modes: fails if the referenced workspace cannot be resolved or the alias conflicts.
Inputs: alias_uri (required), workspace_id_or_uri (required), reason, metadata. Returns: object
Purpose: Release active file reservations after work is done or abandoned. When to use: call at handoff, task completion, or when a stale reservation should be cleared. Inputs: workspace_id plus reservation_id or file_path, optionally scoped by agent_name. Side effects: updates reservation state and audit events. Output: count of released reservations. Failure modes: returns zero when no matching active reservation exists.
Inputs: workspace_id (required), file_path, agent_name, reservation_id. Returns: object
Purpose: Release active symbol reservations. When to use: call after finishing work on a function, class, API, or other reserved symbol. Inputs: workspace_id plus reservation_id or symbol, optionally scoped by agent_name. Side effects: updates reservation state and audit rows. Output: count of released symbol reservations. Failure modes: returns zero when no matching reservation exists.
Inputs: workspace_id (required), symbol, agent_name, reservation_id. Returns: object
Purpose: Extend active file reservations while work continues. When to use: call before TTL expiry if an agent still owns the edit. Inputs: workspace_id plus reservation_id or file_path, optional agent_name, and new TTL. Side effects: updates reservation expiry and audit rows. Output: count of renewed reservations. Failure modes: returns zero when no matching active reservation exists.
Inputs: workspace_id (required), file_path, agent_name, ttl_minutes, +1 more. Returns: object
Purpose: Extend active symbol reservations while an agent is still editing. When to use: call before TTL expiry for ongoing API or function work. Inputs: workspace_id plus reservation_id or symbol, optional agent_name, and TTL. Side effects: updates reservation expiry and audit rows. Output: count of renewed symbol reservations. Failure modes: returns zero when no matching active reservation exists.
Inputs: workspace_id (required), symbol, agent_name, ttl_minutes, +1 more. Returns: object
Purpose: Reserve files so agents can coordinate parallel edits. When to use: call before modifying files that another agent might also touch. Inputs: workspace_id, agent_name, file_paths, purpose, TTL, and optional override reason. Side effects: creates reservation rows and audit events. Output: reservation status and any conflicts. Failure modes: strict policies may reject conflicts unless an override reason is allowed.
Inputs: agent_name (required), file_paths (required), workspace_id (required), purpose, +2 more. Returns: object
Purpose: Reserve functions, classes, or other symbols for finer-grained parallel coordination. When to use: call before editing shared APIs where file-level reservation is too broad. Inputs: workspace_id, agent_name, symbols, purpose, TTL, and optional override reason. Side effects: creates symbol reservation and audit rows. Output: reservation status and conflicts. Failure modes: strict policy may reject conflicting symbols.
Inputs: symbols (required), agent_name (required), workspace_id (required), purpose, +2 more. Returns: object
Purpose: Summarize relevant reservations, handoffs, lineage, and recent activity before work starts. When to use: call at the beginning of a task to avoid duplicating or conflicting with other agents. Inputs: workspace, intent, optional file paths, symbols, agent name, and limit. Side effects: records an MCP audit event. Output: compact review context with risks, reservations, handoffs, and lineage. Failure modes: returns limited context when workspace history is sparse.
Inputs: workspace_id_or_uri (required), limit, intent, symbols, +2 more. Returns: object
Purpose: Search imported agent transcripts, changesets, and shared development memory for evidence relevant to a question. When to use: use this before editing, reviewing, or explaining repo behavior so the agent can reuse prior context. Inputs: query is the natural-language search text; mode selects keyword, vector, or hybrid retrieval; filters scope the search by workspace or source; rerank can improve ranking. Side effects: records an MCP audit event. Output: compact search hits with snippets, scores, sources, and evidence references. Failure modes: invalid mode raises an error; vector or hybrid search requires an embedding provider and database connectivity.
Inputs: query (required), mode, limit, rerank, +3 more. Returns: result
Purpose: Configure how the workspace handles reservation conflicts. When to use: call during setup or team policy changes before multiple agents edit in parallel. Inputs: workspace_id_or_uri identifies the workspace; reservation_conflict_policy chooses advisory, strict, or override-with-reason. Side effects: updates workspace policy. Output: updated policy record. Failure modes: invalid policy names are rejected.
Inputs: workspace_id_or_uri (required), reservation_conflict_policy. Returns: object
Purpose: Suggest existing workspaces that may match a new alias URI based on identity fingerprints. When to use: call before creating a new workspace for a repo that may have moved. Inputs: alias_uri is the new path; fingerprints are observed durable identifiers. Side effects: none beyond database reads. Output: candidate workspace matches with confidence evidence. Failure modes: returns an empty list when no fingerprints overlap.
Inputs: alias_uri (required), fingerprints (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 30 tools
Each tool has a clear and distinct purpose, with detailed descriptions that differentiate them. Even closely related tools (e.g., reserve_files vs reserve_symbols) target different resource types, and operations like record, list, close are clearly separated. There is no ambiguity between tools.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., close_handoff_summary, get_active_reservations, record_changeset). The verbs describe precise actions, and nouns specify the target resource, making the naming predictable and intuitive.
With 30 tools, the server covers a broad domain including handoffs, reservations, changesets, code graph, workspace management, and activity logging. While the count is on the higher side, each tool serves a distinct operational need, and the number is justified by the scope of the protocol.
The tool set covers most lifecycle operations for the domain: CRUD for handoffs (create, list, close), reservations (create, release, renew, list), changesets (record, retrieve), and workspace configuration (get, set). Minor gaps exist (e.g., no explicit update handoff or delete workspace), but these are not critical for the intended agent coordination use case.
Shared, scoped, reviewable team memory for AI coding agents.
Shared memory for AI agents, as a graph in your own Postgres. Writes never call an LLM.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared project memory for coding agents: decisions, lessons, guardrails and tasks per repository.