CRMy

Quick Start

Install CRMy and create a local demo-ready workspace:

curl -fsSL https://raw.githubusercontent.com/crmy-ai/crmy/main/scripts/install.sh | bash

The installer sets up the CLI, database, optional demo data, health checks, a connector-free quickstart proof, and the local web server in a guided flow.

Already have PostgreSQL?

curl -fsSL https://raw.githubusercontent.com/crmy-ai/crmy/main/scripts/install.sh | bash -s -- \
  --database-url "$DATABASE_URL"

After install, open a new shell or use the exact crmy path printed by the installer:

crmy server start
claude mcp add crmy -- crmy mcp
codex mcp add crmy -- crmy mcp

Use crmy server status, crmy server logs --follow, and crmy server stop to manage the background server.

Prefer the manual path, or want to see exactly what gets seeded? Use the Local Demo below.

Related MCP server: Memclaw

Why CRMy

Your AI sales, CS, support, and RevOps agents can draft content, summarize meetings, and call APIs. The hard part is deciding what they are allowed to trust and what they are allowed to do. Raw customer context is unbounded and unvalidated: CRM fields and pasted transcript snippets do not tell an agent whether a claim came from the customer, whether it is stale, whether it conflicts with another source, or whether a proposed action needs approval.

Without a governed context layer, agents can't answer the most critical questions:

• Did the customer actually say this, or did we infer it?

• Is there evidence behind this risk, commitment, or next step?

• Is this CRM field still current?

• Is this actor (agent) allowed to see or change the record?

• Does this customer email, CRM update, or record change need human approval?

• What proof should exist after the agent acts?

CRMy answers these questions before the agent acts. Instead of dumping raw records into a prompt, it gives the agent source-grounded context, freshness and policy checks, action boundaries, human-review paths, and receipts. That makes CRMy useful when an agent is moving from "summarize this account" to "draft the customer email," "update the forecast," "create the handoff," or "write back to the CRM."

In short, CRMy turns messy customer context into safe, provable agent action:

Messy customer context  ->  Governed context  ->  Safe agent actions  ->  Proof at every step

Want proof? Try the local demo below to see an agent resolve a customer, get a governed briefing, check what is safe to act on, and prove lineage.

CRMy is built for teams creating customer-facing agents that need production-grade context discipline around real GTM data.

CRMy does not replace your CRM, warehouse, mailbox, calendar, support desk, or sales methodology. Those systems remain where work happens and state is stored. CRMy makes that state agent-operable.

Who CRMy Is For

Use CRMy when you are building agents that need customer context they can trust before acting.

• Sales and CS agents that draft customer emails, prep meetings, or summarize account state.

• RevOps and support agents that update CRM records, create handoffs, or coordinate governed actions.

• Agent platforms that need evidence, stale-context warnings, approvals, and audit receipts around customer-facing work.

• Teams that want to test governed customer memory with realistic demo data or direct context ingestion.

Local Demo

Local setup usually takes 2-5 minutes if Docker and Node.js are already installed.

You need Node.js 20+ and PostgreSQL. For local development, pgvector is recommended but not required.

Start Postgres:

docker run --name crmy-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=crmy \
  -p 5432:5432 \
  -d pgvector/pgvector:pg16

Initialize and run CRMy:

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/crmy
export CRMY_ADMIN_EMAIL=admin@example.com
export CRMY_ADMIN_PASSWORD="$(openssl rand -base64 24)"
printf 'CRMy admin password: %s\n' "$CRMY_ADMIN_PASSWORD"

npx -y @crmy/cli init --demo
npx -y @crmy/cli quickstart
npx -y @crmy/cli server

quickstart seeds realistic demo data and runs the path an agent takes over MCP: resolve a customer, get a governed briefing, check Action Context, and prove lineage. Use npx -y @crmy/cli doctor for setup health checks such as database, migrations, model readiness, secrets, and port availability.

Model choices come from a built-in catalog plus optional provider discovery. Run npx -y @crmy/cli models refresh --provider openrouter or --provider ollama to update selectable models; discovered models remain review-only until crmy certify passes for that exact provider/base URL/model.

To certify a bring-your-own or newly released model for automatic Memory, follow the Model Evaluation and Certification guide. Certification runs the live model eval suite and only unlocks automatic Memory when the exact provider/base URL/model passes with recorded evidence.

Representative output:

✓ Demo workspace ready: 2 accounts · 6 Signals · 5 Memory
✓ Resolved account "Northstar Labs"
✓ Briefing returned 4 Memory items, 3 activities, and 2 reviewable Signal sets
✓ Action Context returned warn mode, review_needed readiness, 2 recommended actions
✓ Lineage returned source-to-context proof (67 nodes, 395 edges)

Open:

Web UI   http://localhost:3000/app
REST     http://localhost:3000/api/v1
MCP      http://localhost:3000/mcp
Health   http://localhost:3000/health

Demo users:

Admin   sample.admin@crmy.local / crmy-demo-123
Manager sample.manager@crmy.local / crmy-demo-123
Rep     sample.rep@crmy.local / crmy-demo-123
Peer    sample.peer@crmy.local / crmy-demo-123

Start with the Admin user if you want to explore the whole workspace.

Prefer individual commands? They map one-to-one to the MCP calls an agent makes:

npx -y @crmy/cli briefing "account:Northstar Labs"
npx -y @crmy/cli action-context "account:Northstar Labs" --action customer_outreach
npx -y @crmy/cli context lineage --subject "account:Northstar Labs"

Connect an MCP client to the same path:

claude mcp add crmy -- npx -y @crmy/cli mcp
codex mcp add crmy -- npx -y @crmy/cli mcp

Want to watch your own messy text become reviewable context? New extraction from notes or transcripts requires a Workspace Agent model. Once configured, ingest a transcript and see it become evidence-backed Signals. CRMy will not auto-confirm Memory unless the evidence is grounded in the source:

cat > /tmp/northstar-note.txt <<'EOF'
Northstar call: Maya is pushing for expansion, but security review is the blocker.
They need technical validation before Friday. Procurement is not involved yet.
EOF

npx -y @crmy/cli context ingest --subject "account:Northstar Labs" --file /tmp/northstar-note.txt
npx -y @crmy/cli context signal-groups

Prefer interactive setup?

npx -y @crmy/cli init

What init --demo does:

1. Connects to PostgreSQL.

2. Creates the local database when needed.

3. Prepares the CRMy database tables.

4. Creates the first owner account.

5. Generates persistent JWT and stored-secret encryption keys.

6. Writes local CLI and MCP config.

7. Configures the Workspace Agent automatically when local Ollama is running with an installed model.

8. Seeds demo data so the examples work immediately.

For CI or another fully headless setup, use init --yes --demo. For a clean workspace without sample data, use init --yes --no-demo.

Prefer a global install?

npm install -g @crmy/cli
crmy init
crmy doctor
crmy server start

How It Works

flowchart LR
  A[Context Sources]
  B[Signals]
  C[Memory]
  D[Briefing]
  E[Action Context]
  F[Agent Action]
  G[Handoff or Review]
  H[Audit and Lineage]
  K[Trusted Facts]

  A --> B
  B --> C
  B --> D
  C --> D
  K --> D
  D --> E
  E --> F
  E --> G
  F --> H
  G --> H
  A --> H
  B --> H
  C --> H
  K --> H

CRMy keeps customer context useful without pretending messy source material is instantly true.

• Sources are source material before extraction: transcripts, emails, notes, meetings, system of record changes, docs, support/product signals, and agent inputs.

• Signals are inferred claims with evidence, confidence, source lineage, and readiness.

• Memory is evidence-backed customer context that has cleared CRMy's checks, so agents can rely on it across sessions. Time-sensitive Memory carries a review date and surfaces stale warnings, so aging context gets re-checked instead of silently being treated as current.

• Trusted Facts are the optional governed retrieval boundary for approved company, product, pricing, security, implementation, and competitive facts. They keep shared business and product knowledge separate from customer Memory while giving agents cited facts they can safely use.

• Briefings answer: what should the agent know?

• Action Context answers: is this action ready, allowed, risky, stale, or review-required?

• Handoffs and Writeback keep approval, idempotency, audit, and execution receipts in the path when work touches a customer or system of record.

What Agents Get Back

CRMy does not return a raw data dump. It returns a compact packet that separates durable facts from unresolved claims and action risk:

Memory
- Security review is the active expansion blocker.
- Maya is the current expansion champion.

Signals needing review
- Procurement is not involved yet.
  Evidence: "Procurement is not involved yet."
  Status: grounded in source, not confirmed as Memory.

Stale warnings
- Expansion timeline has not been reconfirmed recently.

Safe to act?
- Customer outreach is allowed.
- Include technical validation as the next step.
- Keep the procurement claim out of committed CRM updates until confirmed.

Core Capabilities

How CRMy Reduces Token Use

Most agents fail on customer work because they get too much unverified data, not too little. CRMy sends the agent a ranked, evidence-backed packet scoped to the next action instead of dumping the customer database into the prompt.

• It separates what's confirmed from what's still an unresolved Signal, a stale warning, or a risky claim, so the agent knows what it can rely on.

• It retrieves by action through briefing_get and action_context_get, ranks the highest-value context first, and reports what it left out.

• It attaches source evidence by default, with full Lineage and Source receipts available on demand.

• Agents can choose budget profiles (tiny, standard, deep, evidence_heavy) when they need a tighter or deeper packet.

• Evidence can travel as compact summaries by setting evidence_mode: "summary" while still preserving lineage for inspection.

Advanced users can tune what gets packed (context radius, token budget, evidence detail) and narrow the tool set per session, but sensible defaults mean you rarely need to.

Connect Agents Through MCP

CRMy is MCP-native. Local agent clients can usually start CRMy over stdio:

claude mcp add crmy -- npx -y @crmy/cli mcp
codex mcp add crmy -- npx -y @crmy/cli mcp

Claude Desktop, Cursor, Windsurf, and other MCP clients can use the same command:

{
  "mcpServers": {
    "crmy": {
      "command": "npx",
      "args": ["-y", "@crmy/cli", "mcp"]
    }
  }
}

Remote clients, including ChatGPT Developer Mode, need a reachable CRMy server and the HTTP MCP endpoint:

https://<your-crmy-host>/mcp
Authorization: Bearer <CRMy API key>

Ask a connected agent:

Use the CRMy MCP tools to resolve the customer record "Northstar Labs", get a briefing, get Action Context for customer outreach, list Signals that need attention, check lineage outcomes, and tell me the safest next action with the evidence you used.

Common first tools:

Use scoped API keys for agents whenever possible. Ordinary customer-reasoning agents should see a small workflow-specific tool set, not the full admin/operator catalog.

Focus the tool catalog per session

CRMy exposes a large tool catalog. Registering all of it on every session hurts tool-selection accuracy and wastes context, so you can narrow the working set to the job at hand with a toolset. Toolsets are chosen per connection, not baked into the API key, so the same key can open a customer_outreach session and a systems_writeback session and get the right tools for each.

# stdio (CLI): pick a toolset for this session
crmy mcp --toolset customer_outreach        # or: CRMY_MCP_TOOLSET=ops crmy mcp

# HTTP MCP: per-connection query param or header
POST https://<your-crmy-host>/mcp?toolset=customer_outreach
X-CRMy-Toolset: customer_outreach

Selection only ever narrows what the actor's scopes already allow. It can never widen access, and per-call scope enforcement is unchanged. Every session defaults to the lean Core Profile standard set. Pass --toolset full, ?toolset=full, or set CRMY_MCP_DEFAULT_TOOLSET=full when an operator explicitly needs the full catalog. Call tool_guide to see available toolsets and the one that matches your workflow.

See MCP tools for the full tool catalog and scoped-access model.

CLI And REST

Friendly CLI commands cover setup, demos, Source ingestion, activity/email review, systems, knowledge retrieval, and operational QA.

crmy init
crmy doctor
crmy server start
crmy seed-demo --reset

crmy briefing "account:Northstar Labs"
crmy action-context "account:Northstar Labs" --action customer_outreach
crmy context signal-groups
crmy context lineage --subject "account:Northstar Labs"
crmy knowledge retrieve "vendor lock-in objection" --subject "account:Northstar Labs"
crmy tools describe action_context_get

Update the CLI without touching your config, database, or demo data:

crmy update

If a server is running, restart it after updating. Prefer npm directly? Use npm install -g @crmy/cli@latest.

REST endpoints live at:

http://localhost:3000/api/v1

Use REST for integrations that cannot run MCP or for custom web tooling.

Authorization: Bearer <jwt-token>     # human login
Authorization: Bearer crmy_<api-key>  # agent or integration

Web App Surfaces

Architecture

packages/
  shared/   @crmy/shared   TypeScript types, Zod schemas
  server/   @crmy/server   Express, PostgreSQL, REST, MCP HTTP
  cli/      @crmy/cli      Local CLI and stdio MCP server
  web/      @crmy/web      React app at /app
docker/                    Dockerfile and docker-compose.yml
examples/                  Copy-paste agent harness setup examples
docs/recipes/              Agent walkthroughs

Design choices:

• MCP-first: agents use tools, not brittle app-specific glue.

• PostgreSQL-backed: durable state, migrations, audit, and optional pgvector retrieval.

• Typed Memory: customer-facing operational context instead of generic chatbot memory.

• Scoped actors: members, managers, admins, owners, and agents see only what they are allowed to see.

• Evidence and lineage: important claims point back to source material.

• Grounded promotion: a Signal becomes Memory only when its evidence is actually present in the source, so model confidence alone never mints trusted context.

• Governed writes: mutating actions use idempotency, policy, approvals, and audit receipts.

• Direct ingestion paths: demo data, CLI, MCP, REST, and UI context input all exercise the same briefing, Action Context, and lineage engine.

• Runtime-neutral: the same engine serves MCP, REST, CLI, and the Web UI, so any agent runtime gets the same governed contracts.

• Local-first model support: Workspace Agent configuration can use local or OpenAI-compatible providers.

Configuration

crmy init generates sane local defaults for JWT and secret encryption keys. Production, container, and hosted deployments should set stable secrets explicitly.

Minimum local environment:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/crmy
CRMY_ADMIN_EMAIL=admin@example.com
CRMY_ADMIN_PASSWORD=<strong-password>

Common production essentials:

JWT_SECRET=<stable-random-secret>
CRMY_ENCRYPTION_KEY=<stable-32-byte-base64-or-hex-secret>
CRMY_PUBLIC_URL=https://<your-crmy-host>
CRMY_CORS_ORIGINS=https://<your-web-origin>
CRMY_MIGRATION_MODE=validate

For production deploys, run crmy migrate run as a one-shot migration job before starting web/worker processes. Local installs keep automatic startup migrations by default.

Common timeout controls:

See .env.example for the full reference, including hosted OAuth, mailbox/calendar, semantic retrieval, rate limits, MCP session routing, provider timeouts, and connector settings.

Before claiming live Google or Microsoft mailbox/calendar support for a production tenant, run the provider certification checklist. Automated tests cover CRMy's contracts and failure handling; live provider certification verifies real OAuth consent, sync, draft, send, reply, calendar, and availability behavior against a sandbox or production app.

Develop From Source

git clone https://github.com/crmy-ai/crmy.git
cd crmy
npm install
npm run build

Run the local dev stack:

npm run dev

This starts:

• API server on http://localhost:3000

• Vite web app on http://localhost:5173

Useful checks:

npm run lint
npm run build
npm test
npm run test:cli-coverage
npx playwright install chromium
npm run test:ui-smoke   # with CRMy running on http://localhost:3000

Community And Contributing

• Join the Discord for questions, examples, and implementation discussion.

• Open a GitHub issue for bugs, missing docs, confusing setup, or agent workflows CRMy should support.

• See CONTRIBUTING.md before opening a pull request.

• Share sanitized transcripts, notes, expected Signals, missed context, and false positives. Real agent workloads make CRMy sharper.

Learn More

Docs:

• Guide

• Context Engine

• MCP tools

• Agent recipes

• Examples

• 0.8-1.0 roadmap

Agent examples:

• Claude Code account briefing example

• Claude Desktop account briefing example

• ChatGPT Developer Mode account briefing example

• Codex account briefing example

• Hermes Agent account briefing example

• OpenClaw plugin account briefing example

Recipes:

• GTM agent demo

• Post-meeting agent

• Pipeline review agent

• Outreach agent

• Context governance agent

• Renewal risk agent

• Public signal research agent

Release

Current version: 0.9.5

Release notes live in RELEASE_NOTES.md. Older release notes live in CHANGELOG.md.

License

Apache-2.0