Shared operational brain for teams of AI coworkers.
Getting Started · Architecture · Building an Expert · Usage · Changelog
PearScarf is the shared operational brain for your AI coworkers — a knowledge graph of the work your team has actually done, sourced from the systems where the work lives, not from what someone said about it in a thread. Every coworker reads from the same view; none of them rebuild context on every run.
It separates observed reality (what shipped, what's true now) from stated intent (commitments, plans, goals) — so coworkers don't confuse a promise with a delivery.
Most agent-memory tools learn from conversations — a noisy log of one assistant's exchanges with one user. Your operation lives elsewhere: in Linear issues, Gmail threads, GitHub PRs, calendar events, CRM updates, Spreadsheets. PearScarf reads from those systems directly and keeps the connections between them in a graph. Vector retrieval over raw records loses those connections; hand-maintained markdown systems go stale.
PearScarf watches your operational systems — Linear, Gmail, GitHub — and extracts structured facts with full provenance. Nothing silently overwritten, history always preserved. When a coworker needs context, it asks PearScarf. One call returns everything known about an entity: current state, recent activity, open commitments, blockers — sourced and dated.
PearScarf is itself a multi-agent, self-evolving system with conversational, mcp interfaces. It captures and maintains the state of your operation so your other coworkers don't have to.
For MCP-compatible frameworks
Connect once via MCP. Every coworker in your fleet reads from the same shared brain.
PearScarf uses a plugin system called experts. Each expert is a self-contained package that owns two-way access to a data source:
- gmailscarf — Gmail via OAuth API
- linearscarf — Linear via GraphQL API
- githubscarf — GitHub via REST API
Experts are installed, versioned, and managed independently. Building a new expert requires no changes to PearScarf core — just a manifest, a connect module, and knowledge files.
experts/gmailscarf/
├── manifest.yaml # declares record types, schemas, entry points
├── gmail_connect.py # API client + tools + record ingestion
├── gmail_ingest.py # background polling loop
├── schemas/email.json # JSON Schema for the email record type
└── knowledge/
├── agent.md # LLM agent prompt
└── extraction.md # source-specific extraction guidance
One-command install — clones the source, generates a local .env with auto-random DB passwords, builds the image, and brings the stack up:
bash <(curl -fsSL https://raw.githubusercontent.com/pearshape-ai/pearscarf/main/install.sh)You'll be asked for an Anthropic API key (for extraction) and an OpenAI API key (for embeddings); the installer auto-generates the DB passwords. Pre-req: Docker daemon running. On success, the MCP URL prints to stdout — paste it into claude-workforce's installer to bring up an AI workforce against this PearScarf.
To uninstall: cd into the install directory and bash uninstall.sh (or run the same curl one-liner pattern with uninstall.sh). Destructive — stops containers, wipes data + the install directory entirely.
After install, the UI is at http://localhost:3000 — a view of the operational graph: reality records, intent tree, fact log, self-improvement traces. Ships with PearScarf, comes up with docker compose up. Override the port via UI_PORT in .env if 3000 is taken.
For finer control — full stack in containers, you author the .env yourself:
# Fill in env/.env at minimum: ANTHROPIC_API_KEY, OPENAI_API_KEY, POSTGRES_PASSWORD, NEO4J_PASSWORD
docker compose up -d
docker compose logs -f pearscarfThis brings up Postgres, Qdrant, Neo4j, and the pearscarf app container — auto-installs the shipped experts and exposes the MCP server on port 8090.
For iterating on pearscarf itself — run the app on your host, DBs in Docker:
uv sync
source .venv/bin/activate
docker compose up -d postgres qdrant neo4j # skip the pearscarf container
# Install experts
psc install ./experts/gmailscarf
psc install ./experts/linearscarf
psc install ./experts/githubscarf
# Configure credentials
psc expert auth gmailscarf # Gmail OAuth setup
# Edit env/.linearscarf.env # add LINEAR_API_KEY
# Edit env/.githubscarf.env # add GITHUB_TOKEN + GITHUB_REPO
# Optional: tell the extraction agent about your world
# cp docs/onboarding.example.md env/onboarding.md && $EDITOR env/onboarding.md
# Then set ONBOARDING_PROMPT_PATH=env/onboarding.md in env/.env
# Run
psc run # start system + REPL
psc run --poll # also start expert ingesters
psc dev --poll # Local-dev monolith: Discord frontend + all services + ingesters| Command | Description |
|---|---|
psc run |
Assistant + experts + session REPL |
psc run --poll |
Full system + expert ingesters |
psc dev |
Local-dev monolith: Discord + all services in one process |
psc dev --poll |
Monolith + expert ingesters |
psc discord start |
Discord frontend service (decomposed runtime) |
psc install <path> |
Install an expert package |
psc update <name> |
Update an installed expert |
psc expert list |
List installed experts |
psc expert inspect <name> |
Show expert details |
psc expert auth <name> |
Run an expert's auth flow (e.g. gmailscarf) |
psc expert start-ingestion <name> |
Run an expert's ingester standalone |
psc expert ingest --seed <file> |
Ingest a seed file |
psc expert ingest --record <file> --type <type> |
Ingest JSON records |
psc eval --dataset <path> |
Run eval against a dataset |
psc extraction start |
Run the extraction consumer standalone |
psc triage start |
Run the triage agent standalone |
psc mcp start |
Run MCP server standalone |
psc erase-all |
Wipe all system state |
Two pearscarf stacks run side by side: the dev stack (docker compose up) and an isolated test stack on alt ports for repeatable integration tests.
# one-time: copy the example config
cp env/.test.env.example env/.test.env
# bring up the isolated test stack — postgres / neo4j / qdrant on alt ports,
# under docker compose project name `pearscarf-test`
scripts/test-stack.sh up
# run integration tests against it
uv run pytest --integration
# wipe state + restart for a clean run
scripts/test-stack.sh reset
# tear it down (removes volumes + bind-mount data)
scripts/test-stack.sh downIntegration tests live under tests/integration/ and are marked @pytest.mark.integration — a bare pytest run skips them. CI continues to run unit tests only (pytest tests/unit/).
scripts/benchmark.sh runs an ER eval against the test stack and lands the report (and optionally per-record LLM traces) under data/test/benchmark-debug/.
# requires a real ANTHROPIC_API_KEY in env/.test.env
scripts/benchmark.sh /path/to/eval/dataset # one shot
scripts/benchmark.sh /path/to/eval/dataset --debug # plus LLM prompts/responses
scripts/benchmark.sh /path/to/eval/dataset --no-reset # run against current stack state
BENCHMARK_DEBUG_DIR=/tmp/bench scripts/benchmark.sh … # override artifact locationEach run captures stdout/stderr to <BENCHMARK_DEBUG_DIR>/<timestamp>.log. In debug mode, psc eval --debug-dir <BENCHMARK_DEBUG_DIR> writes a sibling <dataset>_v<ver>_<timestamp>/ containing every LLM prompt and response.
- Getting Started — installation, credentials, first run
- Examples & Usage — three patterns: agents pushing records, polling external systems, adding your own source
- Architecture — system design, expert contract, startup flow, prompt composition
- Building an Expert — step-by-step guide to creating a new expert
- Deployment Vocabulary — declare deployment-specific entity types and fact_types via
vocab.yaml - Usage — full command reference
- Data Model — entities, fact types, full schema, bi-temporal model
- Query Surface — MCP tools reference
- MCP Clients — connect Claude Code, Claude Desktop, or a custom client
- Eval Metrics — extraction precision, recall, entity resolution accuracy
- Changelog
See ROADMAP.md for the current direction and milestones.
Released under the MIT License.
Contributions welcome — see CONTRIBUTING.md. First-time contributors sign a one-click CLA via cla-assistant.io.
Open source · Framework-agnostic · Built on Neo4j, Postgres, Qdrant