Pluribus

Pluribus is the open control plane for governed AI memory: Postgres-backed durable rows, situation-shaped recall, pre-change enforcement, and curation—without treating chat or logs as source of truth.

Recall is the name of the model and doctrine this repository embodies (constraints, decisions, patterns, failures, and related kinds that outlast any single session). Pluribus is the runnable service—HTTP API, MCP, shared global memory pool—described in docs/memory-doctrine.md.

Usage: Pluribus only accumulates memory if the agent runs it every substantive pass.
Default loop: recall_context → plan → act → record_experience.
Skip recall or skip record and you get no durable progress—same as amnesia.

What this is
Why use it
Quick start (Docker — recommended)
Using Pluribus with AI agents
Ensuring your agent uses Pluribus
Using Pluribus with AI editors and agent systems
SDKs for custom agents (Go + Python)
MCP configuration by client
Multi-agent shared memory
Installation paths
Configuration
Everyday API usage (smoke)
Documentation map
Repository layout
Verification and development
Contributing

What this is

One HTTP API (port 8123 in the default stack) for memory lifecycle, recall bundles, enforcement, and related workflows.
MCP over HTTP at POST /v1/mcp on the same base URL—service-first MCP is canonical; stdio MCP is compatibility-only.
Global memory pool in Postgres (with pgvector for optional semantic retrieval). Correlation is tags + retrieval text, not per-agent silos.
Repo governance files (constitution.md, active.md, workorders/, evidence/) describe how this repository uses recall; Pluribus is the engine you can run for any codebase or team that adopts the same discipline.

Canonical product model: docs/memory-doctrine.md · System shape: docs/architecture.md

Why use it

| Benefit | What it avoids | |--------|----------------| | Continuity | Re-deriving the same constraints and failures every session | | Shared truth | Fragmented “memory” trapped in one editor or one chat | | Authority-aware recall | Flattening everything into one similarity score | | Enforcement before risky edits | Shipping changes that violate stated decisions or patterns | | Curated learning | Promoting noise; the loop favors validated, typed statements |

Quick start (Docker — recommended)

Prerequisites: Docker Compose v2, curl (optional: jq).

From the repository root:

docker compose up -d

This starts Postgres (pgvector image), Redis, and controlplane on http://127.0.0.1:8123. On boot the API waits for the database, applies embedded baseline SQL, and verifies core tables. Data persists in the recall_pgdata volume until you remove it.

Check that it is up:

curl -sS http://127.0.0.1:8123/healthz
curl -sS http://127.0.0.1:8123/readyz

Both should return ok when startup has finished.

Prefer a published image (no local build)? Use docker-compose.install.yml and a registry image—see INSTALL.md and docs/pluribus-container-install.md.

Reset the dev database completely (destructive): docker compose down -v then docker compose up -d. Pre-release builds assume a fresh or disposable Postgres; there is no GA-grade versioned migration story yet—see INSTALL.md.

Using Pluribus with AI agents

Point every client at the same API base URL (default http://127.0.0.1:8123). The process is concurrent; Postgres is the shared store. Protocol details: docs/mcp-service-first.md.

Using Pluribus with AI editors and agent systems

Pluribus is MCP-first for agents: institutional memory and cognitive extension—not a generic side tool. REST remains the service, test, and admin boundary.

Why integrate early: recall and episodic ingest work best when they are default habits—see docs/integrations/README.md and docs/memory-doctrine.md.

Each integrations/<platform>/ pack includes a pointer rules.md, editor-native templates where applicable, integrations/pluribus-instructions.md (canonical loop text), skill.md, README.md, and usually mcp-config.example.json—directive templates, do not commit secrets.

Cursor (full “plugin” pack): integrations/cursor/ bundles MCP JSON (mcp-config.json, no-auth + LAN examples), pluribus.mdc, optional pluribus-stricter.mdc, Agent Skill, prompts.md, commands.md, helper/verify-mcp.sh, and plugin-plan.md (what Cursor actually supports). Prefer user-level ~/.cursor/mcp.json and user rules so Pluribus applies in every repository—see integrations/cursor/README.md.

Optional auth: if the server has PLURIBUS_API_KEY set, send X-API-Key on HTTP MCP and in headers below; if unset, omit them. docs/authentication.md.

SDKs for custom agents (Go + Python)

If you are building your own agent runtime, use the minimal SDKs (recall → work → record):

Examples:

examples/go/minimal_loop/main.go
examples/python/minimal_loop.py

MCP configuration by client

Use these as templates; adjust host, port, and paths for your machine.

Endpoint (HTTP MCP): http://127.0.0.1:8123/v1/mcp (JSON-RPC POST).

Fallback (stdio): build cd control-plane && go build -o pluribus-mcp ./cmd/pluribus-mcp, then run the binary with CONTROL_PLANE_URL=http://127.0.0.1:8123 (and CONTROL_PLANE_API_KEY when auth is on). Same tools as HTTP; prompts/resources are HTTP-only on the service.

Cursor

Global ~/.cursor/mcp.json is ideal so Pluribus MCP is available in every repository you open; use repository-local .cursor/mcp.json only for overrides. Cursor MCP reference.

Preferred — HTTP MCP (no local pluribus-mcp binary):

{
  "mcpServers": {
    "pluribus": {
      "url": "http://127.0.0.1:8123/v1/mcp"
    }
  }
}

With API key (use an env var; do not commit secrets):

{
  "mcpServers": {
    "pluribus": {
      "url": "http://127.0.0.1:8123/v1/mcp",
      "headers": {
        "X-API-Key": "${env:PLURIBUS_API_KEY}"
      }
    }
  }
}

Alternative — stdio (if HTTP transport is unavailable):

{
  "mcpServers": {
    "pluribus": {
      "command": "${workspaceFolder}/control-plane/pluribus-mcp",
      "env": {
        "CONTROL_PLANE_URL": "http://127.0.0.1:8123",
        "CONTROL_PLANE_API_KEY": "${env:PLURIBUS_API_KEY}"
      }
    }
  }
}

Restart Cursor after edits. Troubleshooting: docs/mcp-usage.md.

Claude Desktop

Config file (typical): macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json, Linux ~/.config/Claude/claude_desktop_config.json. Claude usually expects a stdio server—point command at your pluribus-mcp binary and set CONTROL_PLANE_URL.

{
  "mcpServers": {
    "pluribus": {
      "command": "/absolute/path/to/recall/

Pluribus

Install / Use

README

Pluribus

Table of contents

What this is

Why use it

Quick start (Docker — recommended)

Using Pluribus with AI agents

Using Pluribus with AI editors and agent systems

SDKs for custom agents (Go + Python)

MCP configuration by client

Cursor

Claude Desktop