← cMCP home

Agent auto-mapping: Claude memory into cMCP

Q-35 · adopted in the build plan (M-106) · built in stages 1l–1t Research done · recommendation ready Extended to all AI tools 2026-10-05 Automatic saving + two-way sync 2026-10-08 Risk list 2026-10-08
Raised and analysed 2026-10-04; web research by four research agents the same day. Extended 2026-10-05 (all AI tools) and 2026-10-08 (automatic saving and two-way sync). When this was written nothing was built; it has since been built as stages 1l–1t (M-109, M-111), and the build plan records where the build differs.

In short: the recommendation

Update 2026-10-05: the same design now covers every AI tool, not only Claude: OpenAI Codex and ChatGPT, Gemini, GitHub Copilot, Cursor, Groq, local apps and more. The Claude plugin becomes one adapter of a small cmcp helper. See Every AI tool.

Update 2026-10-08: a third part answers two more questions. How does memory reach cMCP without anyone remembering to save it? How does any agent or bot tell cMCP who, where and in which conversation it is, so it gets the latest memory back? See Automatic saving and two-way sync. In short: identity from the sign-in, a small envelope for place and conversation, a cursor for "what changed", and saving at checkpoints by hooks and bot libraries, private first.

Beyond Claude: every AI tool (research 2026-10-05)

The five tool families and how each one connects

Tools with no remote MCP at all: Ollama (app / CLI), DeepSeek app, Meta AI, consumer Microsoft Copilot, and probably Aider. They use REST, the CLI or the bridge through another client.

What the research changed

What cmcp import reads, per tool

Company-wide rollout per tool

• Claude Code: plugin marketplace plus managed settings (force-install).
• Codex: requirements.toml plus committed .codex/config.toml.
• Gemini CLI: extension from a private git repo.
• Cursor: team or enterprise hooks and MCP allow-list (/etc/cursor/hooks.json).
• GitHub Copilot: org MCP registry or allow-list (managed-settings.json, since 2026-08).
• Windsurf / Devin: admin allow-list by server id, so cMCP should always use the stable id cmcp.
• JetBrains: IDE Services policy.
• ChatGPT Business / Enterprise: the admin publishes the app once for the workspace.
• Le Chat, Perplexity Enterprise: admin-added connector.
• Copilot Studio: admin centre plus the data policy.
• Open WebUI, LibreChat: central config.
• Later: listing in the public MCP Registry.

The user journey

The solution in detail

1. How a folder is recognised: several names per project

The research confirmed that tools which recognise a project by its folder path break when the same project sits in a different folder on another machine or in a worktree. Claude Code has open issues about exactly that. The recommended approach copies WakaTime's ordered detection and keeps every name found as an alias of one place:

2. How cMCP chooses the place (extended)

1. Place named in the call (only if the person belongs to it)
2. The app's default place
3. Company mapping (place_mappings, set by someone with the mappings power), now matched on any alias
4. The person's own link: "this fingerprint → that project / space", made with one click and remembered on every machine
5. The person's private space for that fingerprint, created automatically (capped, for example 20 a day)
6. Home team, otherwise Org

The fingerprint arrives in two ways: in a header set by the plugin (X-CMCP-Place: auto:… through Claude Code's headersHelper), or by the session-start hook calling a new /v1/places/resolve. The hook also puts a short context pack into the session (additionalContext). A declared place still never widens access (DD-09).

3. Private spaces

• Who sees it: only the person and their own AI apps (the same app rules as User memory). Not counted in max_projects. Never a back door to shared places: shared places still need the create-places power and the limits.
• Contents: facts, decisions and session summaries for that repo, with provenance (machine, branch, commit). An idea from GitHub Copilot memory: unconfirmed items age out unless used.
• Lifecycle: link to a project, keep private, rename, merge two spaces ("these are the same repo"), or delete.

4. Linking and promotion: ask once

• Suggestions appear when a space's alias matches a company project: same remote, same first commit, same host repo id, or a Jira key that is mapped. They show in the console ("Suggested links") and as one line in the next tool answer.
• Link means future work in that repo reads and writes the project, as far as the person's role allows. Existing space items are offered to the project through the import approval queue that already exists. The lead approves; nothing moves silently.
• If the person is not a project member, the suggestion becomes a request to join, or a request to create the project (sent to an ADMIN or someone with the create-places power).

5. Company repos in bulk (optional connector)

A read-only Bitbucket catalogue connector, set up by the ADMIN with a workspace access token or API token (Bitbucket app passwords are blocked from 9 June 2026):

• lists the repos, their Bitbucket project and their ids;
• suggests "Bitbucket project X → cMCP project X" mappings, which the ADMIN approves in one screen;
• picks up new repos through Bitbucket's webhooks.

For personal GitHub, the same works per person with a read-only token; it only links to that person's spaces.

6. Importing existing Claude memory

Secret scan and redaction run on the machine before upload. Duplicates found on several machines are merged on the server. In real company accounts, any processing on the server uses the local model only. A session-end hook keeps new local memories flowing in afterwards. Only changed files are sent.

Automatic saving and two-way sync (research 2026-10-08)

What the others do

None of these products has an API that the others copy. The closest shared interface is LangGraph's memory store. Licences: Mem0, Graphiti, Letta, Cognee and MemOS are Apache-2.0; Supermemory, LangMem and Hindsight are MIT. Honcho is AGPL, so it can't be used in our core. Memory poisoning is real: published attacks in 2025 and 2026 planted lasting instructions through ordinary chats. So automatic memory needs to show where every item came from and must never act as instructions.

Where each tool lets cMCP save automatically

The envelope: what a caller sends and what cMCP trusts

How it travels:

• REST: as headers. The X-CMCP-* headers that exist today, plus X-CMCP-Conversation, X-CMCP-Run, X-CMCP-Cursor and Idempotency-Key.
• MCP:
  • The same headers. cMCP's /mcp has to start reading them; today it ignores them.
  • One com.example.cmcp/envelope entry in _meta, for bots that build their own MCP requests. The July 2026 MCP spec removed protocol sessions, says per-conversation ids must be sent on every request, and reserves no key for them.
  • Optional tool arguments.
• Conflicts: if a header and _meta disagree, the call is refused, the same way MCP handles its own headers.

The OpenTelemetry names are still marked "development", so cMCP keeps its own names and maps them only in logs.

The two-way loop for a bot (proposed here; built with the bot library in stage 1q)

The change list is worked out for that credential when it is read, so a cursor can never show rows the bot isn't allowed to see. A retry with the same idempotency key returns the first answer instead of saving twice. A long-running agent may keep a stream or a webhook open, but only as a wake-up call; after a gap it always pulls from its last cursor. Bots built on the Claude API can use the Claude memory tool with a handler that stores into cMCP. Python bots get a small client library: start → work → checkpoint.

The two-way loop for Claude Code and other tools with hooks

1. Session start: the hook sends the repo fingerprint and the session id. cMCP returns the context and a cursor, and the hook puts the context into the session. Text that came from cMCP is marked, so it is never saved back as if it were new.
2. Each prompt: the hook sends the cursor. If nothing changed, nothing is added (target under 20 ms). Otherwise only the change is added.
3. After answers (at most about every 20 minutes) and before compaction: the hook may ask the model for 0–5 lasting notes, such as decisions, preferences and where things live. They are saved with the conversation id. This is optional per account, because it costs one short extra turn.
4. Session end: there are only 1–1.5 seconds, so the hook hands everything to a background upload. Changed auto-memory files are copied into cMCP, and the checkpoint returns the newest cursor.
5. Next session on any machine: it starts again at step 1, so the memory follows the person.

Rules we suggest for automatic saving

Can cMCP keep whole conversations? (asked and decided 2026-10-08)

Default rules (cMCP follows these unless noted): fixed means no switch can change it. ADMIN may change means changing it shows a risk notice first.

1. Off by default. ADMIN may change Only an ADMIN can switch it on, in person, after a risk notice. It can be on for the whole account, or narrower: per place (project, client) or per AI app. The setting, who set it and when are all audited.
2. People are told. fixed A line at the start of each session says, for example: "This conversation is kept in cMCP for 30 days (company policy)". The console says the same, and keeping starts only after people have been told.
3. People may pause it. ADMIN may change By default a person can mark a conversation "off the record". Turning this off is a high-risk change, used only where the law or a legal hold requires it.
4. Transcripts are not memory. fixed They are stored as source text. They never go into the context pack, never act as instructions and are never shared. Facts come out of them only through the normal extraction and review, and each fact can link back to the lines it came from.
5. Only the person reads their own conversations. fixed For example, they can search "what did I discuss about X last week?" across all their tools and machines. The ADMIN, other people's apps and bots cannot read them. The company gets access only through a logged break-glass with a reason and a notice to the person (as M-33 plans), or through a legal hold.
6. Stored like everything else, but stricter. fixed Conversations go in their own table with account row security and owner-only access. A conversation held at a client stays behind that client's wall.
7. Cleaned before storing. fixed The secret scan runs on the machine before upload, and tool output such as file contents and command output is cut or capped. ADMIN may change Masking personal data is on by default.
8. Kept only as long as the company sets. ADMIN may change The default is 30 days, with 90 or 365 as options; anything over 30 days shows a risk notice. Conversations are purged automatically, deleted when the person leaves (M-30) unless there is a legal hold, and the person can export their own.
9. Real accounts: fixed they are processed only by the local model (M-46); cMCP never sends a transcript to a cloud model. The switch cannot be turned on for a real account until per-account encryption keys (OpenBao) are in place.
10. Legal check first. fixed To switch it on, the ADMIN confirms that the company's legal or HR advisers approved it. Employment and privacy law, such as GDPR in the EU and UK, may require notice, a clear purpose, short retention and in some countries a staff or works-council agreement. This page is not legal advice.

What it gives: search across a person's past conversations in every tool, better extraction later (with a better model run again on the same text), facts that cite their source, and an archive for compliance. What it costs: little storage, because text compresses and tool output is capped. Extra model time is only needed if extraction runs on the transcripts. Build: a transcripts table (owner-only, retention, legal-hold flag), an append-only upload /v1/conversations/{id}/transcript (idempotent by position), the policy switches with risk notices, owner search, a purge job and a break-glass view. It fits stage 1m (the same hooks) if decided; the Enterprise routes belong in 1o.

What our code has today (code survey 2026-10-08)

Risk notices and the risk list (2026-10-08)

How a risk notice works

1. Every switch has a safe default. Moving away from it counts as "loosening". Moving back to the safe side never needs a notice and takes effect at once.
2. Loosening shows a risk card first. The card says what changes, who is affected, the risks, what stays protected and what to check first.
3. Only an ADMIN can do it, in person. An AI app or bot never can, the same rule as named powers (M-104).
   • Every level: a reason is required.
   • Medium risk: the ADMIN also ticks "I have read the risks".
   • High risk: the ADMIN also needs a sign-in no more than 15 minutes old and must type the switch's name. If the account has a second ADMIN, that ADMIN approves too.
4. The people affected are told in the console and in their AI tool's next answer, through the 1l notice channel. For switches that keep or share more of their data, they are told before it takes effect.
5. Loosened switches stay visible. The ADMIN home page lists every loosened switch with its age, and a monthly reminder asks "still needed?". High-risk switches get an end date (90 days by default) and can be renewed.
6. Everything is audited (this exists today for settings). The web-admin can never loosen an account's switch silently: the account's ADMINs are told.

The risk list

exists means the switch is in cMCP today; planned means it is proposed in this issue. Levels: High means data leaves the company, much wider reading, or invasive access. Medium means wrong memory or standing access. Low means a small, contained effect.

1. Data leaves the company

2. Wider reading inside the company

3. Wrong or poisoned memory

4. Standing access (keys, grants, elevation)

5. Keeping more data, for longer

What every person should know (shown once in the console, and in the manual)

• Don't paste passwords, keys or customer secrets into AI chats. The secret scan helps, but it is not perfect.
• Everything your AI saves shows its source: who, which tool and which model. Items marked "auto-saved" were not checked by a person.
• You can see, correct and delete your own memory, and confirm or drop automatic items in "To review".
• Personal memory is never promoted or shared, and only a logged break-glass with a notice to you can read it.
• When a switch that affects your data is turned on, you are told in cMCP and in your AI tool.
• If an answer seems to be steered by a strange "fact", report it: it may be planted text.

What every ADMIN should know

• Every loosened switch makes the attack surface wider. Planted text can turn any write path into a way to poison memory.
• You are an insider risk too, which is why High-risk switches and break-glass need a second ADMIN when one exists.
• Features that keep or read more about people (whole conversations, transcript routes, break-glass) bring legal duties: notice, purpose, retention and possibly a privacy impact assessment.
• Every cloud AI app you allow is a vendor that receives company memory.
• Keys and grants should be short-lived; review the "loosened switches" list every month.

New decisions 20–22 (second ADMIN, end dates, telling people first) are in the Decisions table.

Every Claude surface

Personal device keys (for sessions without a browser)

claude.ai connector checklist:

• 401 with resource_metadata;
• the first authorization server listed is Keycloak;
• the resource exactly matches the MCP address;
• callback https://claude.ai/api/mcp/auth_callback allowed;
• dynamic client registration limited to Claude's addresses, or Client ID Metadata Documents (experimental in Keycloak);
• Keycloak reachable from Anthropic's address range 160.79.104.0/21;
• answers within 10 seconds;
• PKCE.

What changes in cMCP's code

Suggested stages (each with threat model, tests, reviews and approval)

Decisions needed when this is picked up

Research findings (2026-10-04, 2026-10-05 and 2026-10-08)

First analysis (earlier the same day)