puppyone for Claude Code: persistent shared context via MCP

TL;DR

• Claude Code is excellent inside one session — it reads your repo, edits files, runs commands. The moment you /quit or your laptop sleeps, the working memory is gone.
• puppyone gives Claude Code a persistent, version-controlled, multi-tenant workspace via MCP. One config block. Now Claude reads / writes a shared workspace that survives sessions, syncs ingested SaaS data, and is visible to every other agent (Cursor, n8n, your custom code, your teammates).
• The mental model: AGENTS.md and your repo stay in GitHub (Claude Code reads them locally as it always does). Long-form context, ingested SaaS data, agent outputs, and shared notes live in puppyone, exposed to Claude as MCP-mounted files.
• This is the cleanest way we know to give Claude Code a memory that doesn't reset every time you open a new terminal — without overloading the conversation context.

What changes when you add puppyone to Claude Code

Without puppyone, every new Claude Code session starts cold. The agent re-reads your repo, re-discovers your conventions, and any "let me remember that for later" disappears as soon as the session ends. Multi-session workflows (write a spec on Monday, implement it on Tuesday, refactor on Wednesday) lose continuity.

With puppyone wired in via MCP, Claude Code gets:

• A persistent file workspace that survives sessions, restarts, and machine swaps.
• SaaS data as files — Slack threads, Notion specs, Postgres slices show up as readable files in /integrations/..., refreshed on a schedule. Claude reads them with cat, no API gymnastics.
• Multi-agent visibility — anything Claude writes to puppyone is visible to your Cursor agent, your n8n flows, your custom Python agents, your teammates. Same workspace, multiple front doors.
• Per-agent permissions — Claude Code gets its own Access Point with explicit read/write paths. It can't accidentally see (or wipe) data outside its scope.
• Automatic version history — every write Claude makes is a commit with author, timestamp, and diff. Made a bad refactor in /specs/architecture.md? Roll back in seconds.

You're not changing how Claude Code works inside a session. You're giving it a workspace that exists outside the session.

What stays exactly the same

• Your code stays in GitHub. Claude Code keeps reading and writing your local repo as it always has. We're not a code host; see puppyone vs GitHub.
• AGENTS.md stays in your repo. It's the right home for repo-specific instructions. Claude reads it locally; you don't need to re-mount it through puppyone.
• Your prompts, slash commands, and Claude Code config are unchanged.
• Your CI / PR / review flow is unchanged. PRs still go to GitHub. puppyone is the workspace under Claude Code, not a replacement for code review.

How to wire it up (the short version)

1. Create a puppyone workspace. Either cloud (try.puppyone.ai) or self-hosted Docker on your own VPS / Mac mini.
2. Get an MCP endpoint for an Access Point with the path scopes you want Claude to have (e.g. read /specs, /research, /integrations; read+write /scratch/claude-code).
3. Add it to Claude Code's MCP config. A single block in ~/.claude.json (or wherever Claude Code's MCP config lives in your version) pointing to the puppyone MCP server.
4. Inside a Claude Code session, the workspace shows up as a mountable surface — Claude can cat, ls, grep, read_file, write_file against it via the MCP tools.
5. Optional: tell Claude about its workspace in AGENTS.md with a short section like "You have access to a persistent workspace at the puppyone MCP server. Use /scratch/claude-code for working notes, read /specs for current architecture, write summaries of long sessions to /notes/<date>.md." This nudges Claude to actually use the new surface instead of just storing things in conversation context.

(Full step-by-step is in the Claude Code integration guide. This page is the why, not the click-by-click.)

Workflows that actually get better

1. Multi-session feature work

Without puppyone: Monday — Claude Code helps you write a spec. Tuesday — new session, you have to copy-paste the spec back in or hope Claude re-derives it.

With puppyone: Monday — Claude writes the spec to /specs/feature-x.md in puppyone. Tuesday — new session starts; Claude cats /specs/feature-x.md and continues exactly where you left off. The spec is also visible to Cursor, your n8n flow, and your teammate.

2. Long-running research before coding

Without puppyone: You ask Claude Code to research how a library handles X across 30 repos. The output lives in the conversation. End of session, you have to scrape it back out.

With puppyone: Claude writes findings into /research/library-x/ as it goes. Each finding is its own file with a commit. Tomorrow you (or another agent) can grep -r "X" /research/library-x/ and get everything.

3. Multi-agent handoff

Without puppyone: A research agent (n8n + Claude API) drops a markdown file somewhere. Claude Code in your terminal can't easily see it. You manually copy-paste.

With puppyone: Both agents are mounted on the same puppyone workspace. The research agent writes to /research/, Claude Code reads /research/ natively. No manual handoff.

4. Agent identity and audit

Without puppyone: "Who wrote this commit?" → "Some Claude session, I don't remember when."

With puppyone: Every write is keyed to the Claude Code Access Point, with timestamp and full diff. You can audit per-agent activity for compliance, debugging, or just curiosity.

5. SaaS-shaped context inside Claude

Without puppyone: You tell Claude "the auth spec is in Notion, here's the link." Claude can't open links. You paste the content in. Token bloat.

With puppyone: The Notion connector mirrors Auth Spec into /integrations/notion/auth-spec.md. Claude reads it as a normal file. Same for Slack threads (/integrations/slack/...), Postgres slices, GitHub issues, etc.

Patterns to avoid

• Don't try to put your full local codebase into puppyone. That's what your local filesystem (and Cursor / Claude Code's existing repo access) is for. Use puppyone for things that aren't the codebase: long-form context, agent outputs, SaaS data, scratch space, cross-session notes.
• Don't auto-write Claude conversation transcripts to puppyone unfiltered. Most conversation turns are noise. Let Claude write summaries / structured outputs to puppyone, not raw transcripts.
• Don't grant the Access Point write access to your /specs (or any human-curated path) without thinking. The whole point of scopes is that Claude writes to its own area unless you explicitly want it editing canonical docs.
• Don't rely on puppyone for code review. Code changes still go through GitHub PRs. puppyone is the workspace, not the merge gate.

How this fits with the rest of your stack

Claude Code is one of several agents most teams run. The clean topology:

• Claude Code uses puppyone via MCP for persistent context.
• Cursor uses puppyone via MCP — same workspace. See puppyone for Cursor.
• n8n / LangChain / CrewAI workflows use puppyone via REST or its connector layer. See puppyone for n8n and friends.
• Custom Python agents use puppyone via SSH / Bash or REST.

The point isn't to lock you into one editor or framework. It's to give every editor and framework a shared substrate so they stop reinventing per-product memory.

FAQ

Does puppyone replace AGENTS.md? No. AGENTS.md stays in your repo as the per-repo instruction file. Claude reads it locally. puppyone holds the long-form context AGENTS.md can reference but shouldn't contain.

Will Claude Code's context window blow up if I mount a huge puppyone workspace? No — MCP tools are call-on-demand. Claude only loads the files it actually read_files. The workspace can be enormous; only what's read counts.

Can teammates' Claude Code sessions see the same puppyone workspace? Yes — that's the whole point. Each teammate's Claude Code uses its own Access Point (with appropriate scopes), but they all connect to the same workspace. Writes from one are visible to the others.

What about Claude Code's own "memory" features? Claude Code's built-in features (project memory, slash commands, etc.) keep working as before. puppyone is a separate, persistent layer underneath — useful for everything those built-ins don't cover (SaaS ingestion, multi-agent visibility, per-agent identity, etc.).

Do I need puppyone if I'm only ever using Claude Code, alone, on one laptop? Probably not. If you also have a Cursor agent, an n8n workflow, a teammate, or a need for cross-session continuity — yes.

Is the MCP setup hard? It's a few lines of JSON in your Claude Code config. The setup time is single-digit minutes. The win is hours to days per week per agent.

TL;DR (again)

Add puppyone via MCP to give Claude Code the one thing it's missing by default: a persistent, version-controlled, team-visible workspace. AGENTS.md and your repo stay where they are. Long-form context and shared agent state live in puppyone. Same Claude, much longer memory.

Wire Claude Code into a workspace that doesn't reset every session.Get started→