Persistent AI memory for Claude — how global-memory solves the cold-start problem with MCP

The cold-start problem no one talks about

Every conversation with an AI assistant starts from zero. You re-explain your stack, your team, your shorthand, your conventions. After a year of using Claude — or ChatGPT, or Cursor, or any LLM-driven tool — you’ve delivered the same five-paragraph “this is who I am, this is what I work on” preamble several hundred times. The model doesn’t remember. It can’t.

That’s the cold-start problem of conversational AI, and it’s the single biggest reason people give up on these tools after the honeymoon. Templates and saved prompts paper over it. They don’t fix it.

The fix is persistent, retrievable memory: a structured knowledge store the AI reads from on session start and writes to as it learns. Local. Shared across projects. Searchable. Editable in any text editor. Yours.

This post introduces the plugin I built to give Claude exactly that, walks through how it works, and shows real (anonymised) examples of it in action.

What is global-memory?

global-memory is an open-source plugin for Claude Cowork and the Claude Code CLI. It bundles a skill, three slash commands, a session-start hook, and an MCP server registration. Together they give Claude a persistent, cross-project memory backed by plain Markdown files on your local disk.

It’s deliberately small. The whole plugin is a few hundred lines split across a SKILL.md, three command skills, a Bash hook, one shell script, and a JSON manifest. The heavy lifting is done by Basic Memory, an excellent open-source MCP server that handles indexing, search, and retrieval over Markdown notes.

The result feels like Claude finally became a colleague rather than a stranger every morning.

The architecture — Markdown on disk, MCP for access, skill for behaviour

There are three layers, and the separation matters.

Storage layer — plain Markdown. Every fact lives as a Markdown file with YAML front-matter on your local filesystem (default: ~/Documents/Claude/Memory/). One file per person, one per project, one per decision, one per day. No proprietary database. No cloud dependency. You can grep it, version-control it, edit it in Obsidian or VS Code or vim. If the plugin disappeared tomorrow your data would still be there, intact, readable.

Access layer — Basic Memory MCP. A local MCP server reads those files, indexes them in a SQLite database, and exposes a clean tool surface (read_note, write_note, search_notes, build_context, recent_activity) over the Model Context Protocol. MCP is the open standard Anthropic, OpenAI, Google, Cursor, and many others have rallied around for connecting LLMs to tools and data. Because the access layer speaks MCP, the same memory works in Claude Cowork, Claude Code, Cursor, and any other MCP-capable client without changes.

Behaviour layer — a Cowork/Code skill. A forked memory-management skill teaches Claude when and how to use that MCP. Decode shorthand before acting. Promote frequently-used facts to the hot cache. Demote stale items. Append daily journal entries. The skill is what makes Claude actually use the memory consistently rather than treating it as another optional tool.

Five components, in order of how often you’ll use them

1. SessionStart hook — automatic context loading

Every new session, a Bash hook reads the hot cache (CLAUDE.md) directly off disk and injects it into Claude’s context. The hot cache is a deliberately compact ~50–100 line summary: who you are, the top thirty people you talk to, the half-dozen projects you’re actively shipping, the twenty acronyms you use daily.

You don’t trigger this. It just runs. By the time you type your first message, Claude already knows the difference between “Alice” (your platform tech lead) and “Alice” (the customer success contact at the vendor you renewed last month).

2. The memory-management skill — automatic recall and routing

Whenever you say something memory-relevant — a name, a project codename, an acronym, a “remember this” — the skill auto-triggers and walks the lookup chain:

1. Hot cache (already loaded — usually a hit)
2. Full glossary (mcp__basic-memory__read_note with permalink glossary)
3. Person or project deep file (people/<slug> or projects/<slug>)
4. Fuzzy search (mcp__basic-memory__search_notes)
5. Ask you, then write the answer to memory

This is the workhorse. Most days it runs invisibly.

3. /memory-bootstrap — one-time interview-style setup

The first time you install the plugin, run /memory-bootstrap. It asks for your name, role, your most-frequent contacts, your active projects, the acronyms you use daily, and any communication preferences. It then writes seed notes — claude (hot cache), glossary, preferences, plus a people/<slug> and projects/<slug> file per entry.

The bootstrap runs once. After that, you maintain memory through the next two commands.

4. /remember <fact> — explicit fact capture

When a teammate mentions someone new, when a decision is made, when you adopt a new acronym, fire /remember:

/remember Bob Lee just joined as the new platform engineering lead.

The skill classifies the fact (this one is a person), picks the right destination (people/bob-lee), reads the existing file if there is one, merges the new content, writes it back through mcp__basic-memory__write_note, and — if the person is part of active work — promotes them to the hot cache so future sessions have them pre-loaded.

You don’t pick the file. You don’t write the front-matter. You just dump the fact and move on.

5. /memory-wire — wire the pointer block into per-project CLAUDE.md

If you keep per-project CLAUDE.md files (most teams do), /memory-wire walks every one of them under a chosen root and appends a small “global memory exists, here’s how to call it” pointer block. Idempotent — re-runs skip files that already have the marker. One command, one minute, every project Claude opens now knows the global store is available.

Quick start

If you have Homebrew on macOS:

brew tap basicmachines-co/basic-memory
brew install basic-memory
mkdir -p ~/Documents/Claude/Memory
basic-memory project add memory ~/Documents/Claude/Memory --default

Then, in Cowork or Claude Code:

/plugin marketplace add Turek/cowork-global-memory
/plugin install global-memory@cowork-global-memory
/memory-bootstrap

Done. Memory is live, the hook will start firing on every new session, and you can start adding facts with /remember.

Example one — decoding shorthand without re-explaining

Without memory:

User: ask alice to do the PSR for phoenix

AI: I don’t know who Alice is, what a PSR is, or what Phoenix refers to. Could you provide more context?

With global-memory and a populated store:

User: ask alice to do the PSR for phoenix

AI: I’ll draft a Slack message to Alice Chen (your platform lead — prefers Slack DMs, mornings work best) asking her to prepare the Pipeline Status Report for Project Phoenix (the database migration, currently active, $1.2M budget, Q2 launch).

Same input. Two completely different sessions. The second cost about 800 extra tokens at session start (the hot cache pre-load) and saved roughly five minutes of back-and-forth. That ratio compounds.

Example two — capturing a decision

/remember Decided to use Postgres over MySQL for Project Phoenix. Reasoning: better JSON ops, full-text search out of the box, team has more ops experience with Postgres.

The skill writes a new ADR-style note to decisions/2026-05-04-phoenix-postgres-vs-mysql.md with structured frontmatter, the decision body, and links it to projects/phoenix. Six weeks later when someone asks “why did we go Postgres?” the answer is one MCP call away — already classified, already linked, already retrievable.

Example three — wiring a multi-project workspace

/memory-wire

Output:

injected: /Users/me/Documents/Claude/Project1/CLAUDE.md
injected: /Users/me/Documents/Claude/Project2/CLAUDE.md
skipped: /Users/me/Documents/Claude/Project3/CLAUDE.md (already had marker)
injected: /Users/me/Documents/Claude/Project4/CLAUDE.md

Done. Injected: 3. Skipped: 1.

Every project’s per-repo CLAUDE.md now has a small block instructing the AI assistant to call the basic-memory MCP for cross-project context.

Why local-first beats cloud RAG

There’s a class of vendor-hosted “AI memory” products. They’re convenient. They also have problems:

• Vendor lock-in. Your knowledge graph lives in their schema, their database, their cloud.
• Privacy exposure. Personal facts about your team, project specifics, internal acronyms — all uploaded.
• Offline failure. Plane, train, dodgy hotel WiFi: your memory is unavailable.
• Pricing risk. Per-MB or per-query pricing scales badly when memory grows for years.

Local-first inverts every one of those:

• Your filesystem. The data is in ~/Documents/Claude/Memory/. Always.
• No third-party servers. Basic Memory runs as a local process.
• Offline by default. No network needed.
• Free as in speech and beer. Open source: AGPL for Basic Memory, MIT for the global-memory plugin.

Why this beats naive retrieval-augmented generation

Classic RAG pipelines chunk documents, embed them into a vector database, and retrieve top-k matches at inference time. That works for read-only knowledge bases. It struggles for memory because:

• Memory is bidirectional. The AI needs to write new facts, not just retrieve old ones.
• Memory is structured. People, projects, decisions, daily notes — these have schema.
• Memory needs hot vs. cold tiers. Some facts you reference in every session; others once a quarter.

Global-memory’s two-tier structure (CLAUDE.md hot cache + per-topic deep files) plus Basic Memory’s hybrid full-text + vector indexing gets you the best of both worlds.

Trade-offs and token costs

The honest numbers:

• Per-session overhead from the SessionStart hook: ~1,000 tokens for a typical hot cache.
• Per-MCP-call overhead vs. raw Read: ~10–30% more due to JSON envelope.
• Tool schema overhead: minimal in Cowork because tools are loaded on-demand.

Net: roughly break-even for tiny stores, decisively in MCP’s favour as the store grows. The reason to use it isn’t tokens — it’s cross-project access.

When to use, when not to use

Use it if: you live in Claude Cowork or Claude Code, work across multiple projects, frequently re-explain the same context, want memory you can git diff, care about local-first or privacy.

Skip it if: you’re a casual AI user, don’t have consistent context worth remembering, or need cross-machine sync as a baseline feature with zero setup.

Get started

The plugin is open-source on GitHub: Turek/cowork-global-memory.

brew tap basicmachines-co/basic-memory && brew install basic-memory
mkdir -p ~/Documents/Claude/Memory
basic-memory project add memory ~/Documents/Claude/Memory --default

Then in Claude Code or Cowork:

/plugin marketplace add Turek/cowork-global-memory
/plugin install global-memory@cowork-global-memory
/memory-bootstrap

Five minutes from zero to live.