CommonGround Kernel — Tools & Infrastructure

CommonGround Kernel is an open-source ground layer for real human-agent and multi-agent work, providing a durable public record of work across people, tools, services, and runtimes. It solves the problem of work being lost in temporary sessions by preserving shared task state, handoff facts, and evidence for later recovery and reuse. It is for developers building agent systems that need durable, inspectable, and resumable work records.

agents ai ai-agents llm multi-agent-systems multiagent

🐙 View on GitHub ↗ Intelligent-Internet/CommonGround 📦 Install

✨ Key features

Stable agent identity for logical executors
Durable turn boundaries for work units
Turn-owned public semantics for inputs and outputs
Claim fencing and lifecycle management
Causal lineage for parent/child work
Ledger and feed for pull-first inspection

🎯 Use cases

Publishing public work records from local agents
Integrating external runtimes to receive and complete work
Building durable multi-agent collaboration systems
Auditing and recovering work after session loss

📦 Installation

🧰 Requirements: Python >=3.13, uv, PostgreSQL with a writable local database.

uv tool install 'commonground-kernel[server]'

🚀 Usage

Prepare database

export PG_DSN=postgresql://USER:PASSWORD@HOST:PORT/DBNAME

Seed project

cg setup project seed --default-local
cg setup project status --default-local
cg setup project client-config --default-local \
  --base-url http://127.0.0.1:8000 \
  --admin-base-url http://127.0.0.1:8000

Run local bundle

cg local run --project-id cg-demo --host 127.0.0.1 --port 8000

Submit a work report

cat > report.json <<'EOF'
{
  "kind": "agent_work_memory_report_manifest.v1",
  "request_id": "local-agent-report-001",
  "summary": "Local work completed and reported.",
  "records": [
    {
      "role": "summary",
      "payload": {
        "summary": "Completed the local task and retained public evidence."
      }
    }
  ]
}
EOF

cg profile ensure-agent \
  --profile cg-demo/local-agent \
  --project-id cg-demo \
  --requested-agent-id local-agent \
  --profile-kind byoa.work_memory_reporter.v1 \
  --runtime-kind local.cli.v1 \
  --display-name "Local Agent"

cg report work-memory \
  --profile cg-demo/local-agent \
  --project-id cg-demo \
  --agent-id local-agent \
  --manifest-file report.json

⚠️ Good to know

CommonGround Kernel v3r1 is an initial open source preview and is not backward-compatible with the earlier v1 preview; it is not a full agent memory product, runtime, or orchestration framework.

❓ FAQ

What is the minimum durable work boundary in CommonGround?

The Turn is the minimum durable work boundary, representing a unit of work, delegation, interaction, or recovery loop, not just a chat reply or temporary session.

How does CommonGround ensure work is recoverable after sessions disappear?

It preserves durable public facts such as task state, handoff facts, evidence, and causal lineage, allowing later participants to inspect and resume work.

Is CommonGround compatible with v1 previews?

No, v3r1 is a new preview line with breaking changes; v1 source remains on the legacy/v1 branch.

What database does CommonGround require?

It requires PostgreSQL with a writable local database, configured via the PG_DSN environment variable.

📊 Repository

GitHub github.com/Intelligent-Internet/CommonGround

Stars★ 149

Forks🍴 20

Open issues🐛 1

Last commit🕒 May 20, 2026

Created📅 Feb 2026

Language💻 Python

License⚖️ Apache-2.0

Topics agents ai ai-agents llm multi-agent-systems multiagent

🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.