A developer works late at a tidy desk with two monitors and a warm lamp light

Memory for Claude Code and coding agents: MCP, hooks and limits

Product8 min read

How to give Claude Code persistent memory with MCP and hooks: step-by-step setup, what is sent to MemoryFirst, what each session recalls and the limits.

by Equipo MemoryFirst

Table of contents
  1. Two doors: MCP and hooks
  2. What the hooks do, exactly
  3. Step-by-step setup
  4. One session, start to finish
  5. Permission control
  6. Honest limits
  7. Next steps
  8. Sources

You open Claude Code on a Monday and ask it to pick up last week's migration. It answers politely and with no clue: it does not know which table was dropped, why you chose one library over another, or that on Friday you agreed to leave an endpoint alone. It starts cold. We describe that as a problem in your AI agents start cold every session; this guide is the practical fix.

There are two doors for giving a coding agent memory, and the difference is worth understanding before you install anything.

A developer's hands on a mechanical keyboard with a blurred terminal in the background

Two doors: MCP and hooks

MCP turns memory into one more tool. The agent decides when to query it (mf_query, mf_recall) and when to record something (mf_record). It works with Claude Code, but also with Claude Desktop, ChatGPT, Cursor or VS Code, because the server is remote and speaks the standard protocol. There are 15 tools in total; the ones you will use most for programming are recalling a project's state, asking with citations, recording a decision and reading the current state.

Hooks are commands Claude Code runs at points in a session's lifecycle. Here the agent does not decide, the system does: at the start they inject context; at the end they send back what was learned. This is the part that does not depend on the model remembering to ask for memory.

The combination is the good one: hooks cover the automatic part and MCP covers the deliberate part. If you only want one, start with MCP; if you want the one that needs the least daily effort, hooks.

What the hooks do, exactly

This is what the hooks package does, checked against its code on 13 November 2026:

Claude Code eventWhat happens
SessionStartAsks MemoryFirst for the project's context (up to 2,500 tokens by default) and injects it as additional context. If the project has no events yet, it injects nothing
StopSends a snapshot of the conversation text, at most one every 3 hours per session by default
SessionEndSends the final conversation, with no frequency limit

The project is identified by the git repository name (or the folder name when there is none), so a session in a worktree counts against its repository. Each project has its own memory inside your workspace.

What the server does with the conversation: it does not store the dump as is, it distils it into events (decisions, blockers, state) and retires earlier snapshots of the same session so nothing is duplicated. If you send the same text twice, the second one is a no-op.

Step-by-step setup

Step 1: account and key

Create your account and workspace on the sign-up page; data is stored in the EU (Germany). Then generate an API key under Settings, API keys. It is shown only once: keep it in a password manager.

Step 2: connect the MCP server

With an API key:

claude mcp add --transport http memoryfirst https://mcp.memoryfirst.ai --header "Authorization: Bearer mf_live_…"

If you would rather sign in with your account than use a key, add the server without the header and authorise with /mcp inside Claude Code. Do not set the Authorization header if you want OAuth: Claude Code would use the header as the credential and never fall back to OAuth.

Step 3: install the hooks

The onboarding wizard in the dashboard shows the two exact commands: clone the hooks repository it points you to and run ./install.sh --credentials. They need bash, jq and curl, and work on macOS and Linux. When the installer asks for the address and key, they go to the system keychain on macOS and to ~/.config/memoryfirst/hooks.env with 600 permissions on Linux. They are never written into the repository or the hooks.

The installer is idempotent: you can run it again to upgrade. It edits ~/.claude/settings.json by merging only its own entries, leaves other tools' hooks untouched and writes a backup before every change. ./install.sh --uninstall reverses it.

Step 4: check that it works

Open a fresh session in a project that already has some events and check that it starts with context. Every upload is logged, without content or credentials, in ~/.claude/hooks/memoryfirst-ingest.log.

A notebook with a hand-drawn checklist next to a laptop

One session, start to finish

This is an example flow, not a measurement. You resume the billing project on Monday. When Claude Code opens, the start hook injects a summary: Friday's decision not to touch the export endpoint, the open blocker with the payment gateway and the last deploy. You type "carry on with the migration" and the agent already knows which table was dropped. When a new decision comes up, the agent records it with mf_record. If you share a team memory (Team plan) and a colleague asks the next day, from Cursor, why that library was chosen, mf_query answers with a citation to the session where it was decided.

For the cited-answers side, memory you can audit explains what each citation holds; to connect other clients, plug memory into any agent.

Permission control

When you connect a client over OAuth, you decide how much it may do. There are two access levels: read-only (recall, query, see projects and state) and read and write (it also records events and manages tasks). You can limit the connection to specific projects, give it an expiry date and revoke it from the dashboard.

One risk to keep in mind: an agent with write access that reads something malicious (a web page, an email) could be led to write false data into your memory. Give write access only to the application that truly needs it.

Honest limits

  • Best effort and silent. If credentials are missing, the network fails or the API is down, the hooks say nothing and do not break the session. The flip side is that a failure shows up as an absence: a session that starts without context. A watchdog hook flags in one line when the configured MCP key was rotated, because Claude Code reads that configuration only once at startup.
  • Conversation text only. Your messages and Claude's text replies are sent. Tool outputs, the content of files read and thinking blocks are not extracted. Sessions under 400 characters are skipped and each capture is capped at the last 200,000 characters.
  • Distillation goes through a language model. That text is processed by the platform's inference chain, whose default provider is US-based; bring-your-own-key covers queries, not extraction. If your code or conversations have compliance constraints, read this before installing.
  • Secrets should not be in the conversation. The server redacts credential-shaped strings on ingest, but that is no guarantee: do not paste keys into a session.
  • It is not code memory. It does not index or understand your repository; it keeps decisions, state and conversation context. For code, your agent still reads the files.
  • Free plan. 1 project and 30-day retention. If you work across several repositories you will need Pro (12 EUR/month billed annually, unlimited projects and unlimited retention).

One optional detail: if you send the X-MemoryFirst-Session header with the Claude Code session id, queries leave that same session's transcript out and do not echo your own question back as the answer. It depends on your Claude Code version exposing that id; if it does not, the header is ignored.

When you do not need it

If you work alone, in a single repository, and all you want is for Claude to remember your style preferences, a local memory plugin is enough and needs no account. MemoryFirst pays off when memory must cross projects, machines, tools or people, or when you want verifiable citations. There is more in the comparison with Mem0 and in how to choose a memory layer.

Two developers review a problem together at a shared desk in a small studio

Next steps

If you work in a team, read the simulated scenario of a software team with agents. For the whole product, what a company brain is. The technical reference is in the docs.

Sources

  • Claude Code hooks documentation (SessionStart, Stop, SessionEnd events and additional context at start): https://code.claude.com/docs/en/hooks (accessed 2026-11-14)
  • Claude Code MCP documentation (claude mcp add --transport http, headers and authorising with /mcp): https://code.claude.com/docs/en/mcp (accessed 2026-11-14)
  • Hook behaviour and data limits: documentation and code of the MemoryFirst hooks package, checked on 2026-11-13. Prices and plans: MemoryFirst pricing page (accessed 2026-11-14).

Install the hooks in 10 minutes

The Free plan includes 1 project, MCP memory and the Claude Code hooks. Generate your key and try a session.

Start free

Keep reading