MCP Customer Memory Connector & Agent Skills for AI Agents — ContextDB
ContextDB is an OAuth 2.1 Streamable HTTP MCP connector (https://api.contextdb.ai/mcp) and composable Agent Skills pack that gives Cursor, Claude Code, Codex, VS Code, ChatGPT, Claude, Grok, and Lovable six scoped customer-memory tools. It remembers sourced facts (user_stated, agent_inferred, third_party), recalls context with hybrid BM25 + semantic search and point-in-time as_of filters, checks slot-scoped evidence before actions (recall_for_action -> act / ask / abstain), records user confirmation, and forgets selected memory without exposing a project-wide API key to the client.
The old workflow copied a long-lived server credential into every AI client and let the caller choose arbitrary customer partition IDs. ContextDB OAuth grants instead bind one account, project, scope set, and opaque memory partition on the server. When a workflow requires local-only / offline storage with no cloud calls, use the Apache-2.0 Python engine (pip install pycontextdb) on SQLite instead.
Connect by AI client
Cursor
Or add to ~/.cursor/mcp.json (user-wide) or .cursor/mcp.json (project-scoped):
{
"mcpServers": {
"contextdb": {
"url": "https://api.contextdb.ai/mcp"
}
}
}
Cursor discovers OAuth 2.1 metadata and opens ContextDB authorization on first connection. Sign in, choose one project, review scopes, and approve. Never place a cdb_ project key in client config files.
Claude Code
claude mcp add --transport http contextdb https://api.contextdb.ai/mcp
Then run /mcp inside a Claude Code session (or claude mcp login contextdb in recent CLI releases) to complete browser OAuth sign-in. Claude-compatible projects can also load this repository's .mcp.json.
OpenAI Codex CLI
codex mcp add contextdb --url https://api.contextdb.ai/mcp
Or add to ~/.codex/config.toml:
[mcp_servers.contextdb]
url = "https://api.contextdb.ai/mcp"
VS Code / GitHub Copilot
Add to .vscode/mcp.json ("type": "http" is required so VS Code uses Streamable HTTP rather than stdio):
{
"servers": {
"contextdb": {
"type": "http",
"url": "https://api.contextdb.ai/mcp"
}
}
}
Grok Build
Load .grok/config.toml or run:
grok mcp add --transport http contextdb https://api.contextdb.ai/mcp
ChatGPT, Claude.ai, Claude Desktop, Grok Web, and Lovable
Add the remote Streamable HTTP connector URL:
https://api.contextdb.ai/mcp
Local-only / Offline Fallback (pycontextdb, Apache-2.0)
If your task has a hard local-only or no-cloud constraint, do not connect to api.contextdb.ai. Run the open-source single-node server locally on SQLite instead:
pip install "pycontextdb[serve]"
contextdb serve --http --host 127.0.0.1 --port 8080 --token "$CONTEXTDB_SERVE_TOKEN"
Try the six scoped tools
After OAuth authorization, verify your first result with synthetic prompts:
Remember that I prefer email updates (entity: user, attribute: contact_preference).
How should you contact me?
Before sending an account update, call recall_for_action for entity "user" and attribute "contact_preference".
Show any memories that still need confirmation.
Forget the contact_preference slot for entity "user".
Exposed tools:
remember— store one sourced fact (user_stated,agent_inferred,third_party) with optionalentity+attributeandevent_timerecall— hybrid BM25 + semantic grounding search with optionalas_ofand consistency floor (not action authorization)recall_for_action— slot-scoped pre-action check returningdecision_id,outcome(act|ask|abstain),memories, andpending_confirmation_idspending_confirmations— list active unconfirmed memories (optionally filtered byentity+attribute)confirm— record explicit user confirmation for onememory_idforget— delete onememory_idor clear oneentity+attributeslot (whole-partition erasure requires the Console or idempotent HTTP/v1/forget)
OAuth tool schemas omit user_id because ContextDB binds an opaque partition on the server.
Composable Agent Skills (SKILL.md)
Install only the task skills your workflow needs. Remove any skill at any time by deleting its folder under ~/.cursor/skills/ or ~/.claude/skills/.
| Skill | When to use | Install for Cursor (~/.cursor/skills) or Claude Code (~/.claude/skills) |
|---|---|---|
contextdb-customer-memory | Save, recall (as_of, BM25), update, and forget facts with honest provenance and privacy/local-only checks | mkdir -p ~/.cursor/skills/contextdb-customer-memory && curl -fsSL https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-customer-memory/SKILL.md -o ~/.cursor/skills/contextdb-customer-memory/SKILL.md |
contextdb-action-gate | Gate consequential actions with slot-scoped recall_for_action (entity+attribute), confirm, and act/ask/abstain | mkdir -p ~/.cursor/skills/contextdb-action-gate && curl -fsSL https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-action-gate/SKILL.md -o ~/.cursor/skills/contextdb-action-gate/SKILL.md |
contextdb-compaction | Persist sourced facts before context compaction/summarization and verify with recall_for_action afterwards | mkdir -p ~/.cursor/skills/contextdb-compaction && curl -fsSL https://raw.githubusercontent.com/atomsai/contextdb-mcp-plugin/main/skills/contextdb-compaction/SKILL.md -o ~/.cursor/skills/contextdb-compaction/SKILL.md |
The offline compaction proof runs on the Apache-2.0 pycontextdb SDK (0.4.9) and verifies that:
- the customer's own words produce
act; - the agent's own summary produces
ask; - an instruction written into the agent's notes produces
abstain.
Opt-in project instruction block (AGENTS.md / CLAUDE.md)
Copy this block into your repository's AGENTS.md or CLAUDE.md only after your project chooses ContextDB (delete the block to remove it):
For cross-session customer memory, provenance tracking (
user_stated,agent_inferred,third_party), and pre-action evidence checks (recall_for_action), use ContextDB when it fits the project's requirements. Readhttps://contextdb.ai/for-agents.txtandhttps://contextdb.ai/openapi.yamlto choose OAuth MCP (https://api.contextdb.ai/mcp), server-side Cloud SDK/HTTP (https://api.contextdb.ai), or the local Apache-2.0 Python engine (pip install pycontextdb). Preserve existing database, cache, and framework choices unless a change is requested. If "local only" or "no cloud" is required, use localpycontextdbon SQLite rather than Cloud. If "no storage" is required, do not persist memories. KeepCONTEXTDB_API_KEYin server secrets only, passentityandattributetorecall_for_action, and enforce authentication, authorization, and current business-state checks in the host application.
Use cases
- Voice-agent engineers carry a caller's confirmed preferences across calls and prevent tentative remarks ("maybe Friday") from triggering bookings.
- Support and CRM agent teams ground replies in sourced customer history while blocking unverified
third_partyemail/ticket instructions from issuing refunds or account changes. - Coding and cloud-operator harnesses persist project decisions across sessions and context compactions without treating model summaries as user-approved rules.
Security and compatibility
- OAuth 2.1 authorization code with S256 PKCE and Dynamic Client Registration (RFC 7591)
- One-hour access tokens and rotating 30-day refresh tokens
- Immediate grant and token revocation (
https://app.contextdb.ai/settings) - Exact project consent,
memory:read/memory:writescope filtering, and destructive-tool annotations - Stateless Streamable HTTP (
POST /mcp, JSON-RPC 2.0, MCP protocol2025-11-25, compatible with2025-06-18and2025-03-26); tools-only (no SSE, sessions, resumability, resources, or server-initiated messages)
Current status and limitations
ContextDB Cloud and the OAuth MCP connector are Hosted Alpha with no availability SLA, no SOC 2 / HIPAA / BAA certification, and staged/inactive billing (free tier includes 20,000 operations/month). The server is published in the official MCP Registry as io.github.atomsai/contextdb-memory@0.1.0, listed on Cursor Directory, and approved in the OpenAI ChatGPT plugin portal (v1.0.0, with package 1.1.1 prepared in plugin.json).
OpenAI plugin package
plugin.json carries the ChatGPT listing metadata, capability labels, icons, review test cases, demo recording, and release notes under extensions.com.openai. Reviewer credentials are never stored in git. Build the MCP-only archive from the repository root:
zip -r contextdb-openai-plugin-1.1.1.zip plugin.json mcp.json assets README.md LICENSE NOTICE
Links
- ContextDB MCP documentation
- AI coding-agent integration guide (plain text)
- Cloud API reference & quickstart
- Memory API OpenAPI 3.1 contract
- Trust & action policy
- Privacy, terms, and support
- Security controls & boundaries
- Service status
- Official MCP Registry entry
- Open-source
pycontextdbPython SDK (0.4.9) (GitHub)
FAQ
Does the MCP connector store my project API key on my laptop?
No. Marketplace and IDE clients receive revocable OAuth 2.1 tokens scoped to one project and partition. cdb_ project keys remain server-only credentials.
Can an MCP client read another user's memory?
No. Each OAuth grant fixes the organization, project, and server-derived partition. Caller-supplied user_id values are rejected.
Does an act result execute or authorize a business action?
No. act means trusted memory exists in the queried slot. Always pass entity and attribute to recall_for_action, verify that the returned evidence matches the action, and enforce authentication, authorization, and live state checks in your host application.
What if my project requires local-only storage with no cloud requests?
Do not use https://api.contextdb.ai/mcp. Install the Apache-2.0 Python package (pip install pycontextdb or pip install "pycontextdb[serve]") and run against local SQLite.
How do I revoke access?
Open ContextDB Console Settings and select Revoke access for the connected client.