# Membase Use Case 01: Coding Agents — Claude Code Persistent Memory

*Your coding agent forgets every decision when the session ends. Here’s how to give it automatic, long-term memory with three hooks and one install command.*

Published: 2026-10-16 · Updated: 2026-10-28 · Author: Membase Team  
Source: https://membase.com/blog/membase-use-case-01-coding-agents

> Part of **Membase Use Cases**: 17 runnable demos of what long-term memory makes possible. [See all use cases →](https://membase.com/#usecases)

![Membase Use Case 01, Coding Agents: Claude Code persistent memory. Decide something in one session, and a brand-new session already knows it. Works with Claude Code, Codex CLI and Gemini CLI.](https://dmc2j1nsu0tnv.cloudfront.net/1792082160634-Pmej-membase-use-case-01-coding-agents-1.png)

***Quick answer***

*To give Claude Code persistent memory across sessions with Membase:*

1. Get a developer key (mbk_…) in the Membase app under **Connect › Developer keys**.
1. Create a Memory named after your repo, or one named Coding.
1. Run python3 01-coding-memory/install.py claude --key mbk_…
1. Work as usual. Recall happens at session start and on every prompt; the session is saved when it ends.
1. Test it: decide something, quit, open a new session, and ask about it without mentioning it.

*The same steps work for **Codex CLI** and **Gemini CLI**: swap claude for codex or gemini.*

**In this guide:** [Why Claude Code forgets](https://membase.com/blog/membase-use-case-01-coding-agents#why-claude-code-forgets-between-sessions) · [The demo](https://membase.com/blog/membase-use-case-01-coding-agents#see-it-work-a-decision-that-survives-a-new-session) · [Setup](https://membase.com/blog/membase-use-case-01-coding-agents#step-1-get-a-developer-key-and-create-a-memory) · [How it works](https://membase.com/blog/membase-use-case-01-coding-agents#how-the-hooks-work) · [Common mistakes](https://membase.com/blog/membase-use-case-01-coding-agents#common-mistakes) · [FAQ](https://membase.com/blog/membase-use-case-01-coding-agents#faq)

## Why Claude Code forgets between sessions

You spend twenty minutes with Claude Code deciding how invoice numbers should work. You settle it: new numbers are ULIDs made on the device (INV-&lt;ULID>), and old numbers never change. Then you close the terminal.

The next day you open a fresh session and ask about invoice numbering. The agent reads billing/numbering.py, sees max + 1, and suggests you keep incrementing.

The decision never reached the code, so a new session has no way to know it happened. Each session starts from the files on disk and whatever you put in its context.

The usual workarounds each cover part of the problem:

![Table comparing CLAUDE.md or AGENTS.md, the CLI's built-in memory, re-explaining every session, and Membase memory hooks by what each is good at and where it falls short](https://dmc2j1nsu0tnv.cloudfront.net/1792082167039-AMOs-membase-use-case-01-coding-agents-2.png)

Static files and automatic memory work well together: keep stable conventions in CLAUDE.md, and let memory catch the decisions you make while working.

New to Claude Code's memory files? See [How Claude Code memory works](https://membase.com/blog/claude-code-memory) for CLAUDE.md, auto memory and the /memory command.

## See it work: a decision that survives a new session

[01-coding-memory](https://github.com/membaseai/membase-use-cases/tree/main/01-coding-memory) connects your coding CLI to Membase so it remembers **on its own**:

- **Session start:** the agent is told what you decided about this project before.
- **Every prompt:** your message is checked against memory, and anything relevant is added to the context.
- **Session end:** the session is saved.

You don’t run any commands, and the model doesn’t have to decide to use memory.

![Every session saves to Membase; the next session recalls from it.](https://dmc2j1nsu0tnv.cloudfront.net/1792082175483-pZID-membase-use-case-01-coding-agents-3.png)

Every session saves to Membase; the next session recalls from it.

[https://youtu.be/quWcFSea2HE](https://youtu.be/quWcFSea2HE)

Here’s what happens in the video, a real Claude Code run against hosted Membase.

1. **Session 1: you make a decision.** claude -p reads billing/numbering.py. You decide new invoice numbers are INV-&lt;ULID> and old numbers never change.

![Session 1: Claude Code reads the code, and you settle the numbering decision.](https://dmc2j1nsu0tnv.cloudfront.net/1792082194981-uXBP-membase-use-case-01-coding-agents-4.png)

**2. The session ends, and Membase keeps it.** The plugin’s log (top pane) shows it saving the session to a Memory called Coding. Membase learns it in about 26 seconds.

![The plugin saves the session; the status bar shows the Coding memory learning it.](https://dmc2j1nsu0tnv.cloudfront.net/1792082206083-CqfN-membase-use-case-01-coding-agents-5.png)

**3. Session 2: a brand-new process.** clear, then a new claude process. cat billing/numbering.py shows the code still says max + 1. Nothing has carried over.

![A fresh session, and the code on disk still uses max + 1.](https://dmc2j1nsu0tnv.cloudfront.net/1792082225997-obr7-membase-use-case-01-coding-agents-6.png)

**4. It already knows.** The UserPromptSubmit hook adds the decision from Membase to the prompt.

![The hook’s added context, exactly as Claude Code received it.](https://dmc2j1nsu0tnv.cloudfront.net/1792082248416-ka9t-membase-use-case-01-coding-agents-7.png)

## How we kept the test fair

Claude Code’s own auto-memory was **switched off and checked empty** before the run. The code on disk still said max + 1. So the only place the second session could have learned the decision was Membase. Its answer: use INV-&lt;ULID>, and never renumber existing invoices.

![Session 2’s answer, built on a decision it never saw.](https://dmc2j1nsu0tnv.cloudfront.net/1792082262956-2QOS-membase-use-case-01-coding-agents-8.png)

## Step 1: Get a developer key and create a Memory

In the Membase app, open **Connect › Developer keys** and create a key.

![Table of developer key levels: Read & write or Full access recalls memory and saves sessions; Read recalls only, and sessions are not saved](https://dmc2j1nsu0tnv.cloudfront.net/1792082273919-749M-membase-use-case-01-coding-agents-9.png)

Then create a Memory for the project. The hooks pick one in this order:

1. MEMBASE_CONTAINER (a name or id), if you set it
1. A Memory named like your project’s git folder (case doesn’t matter)
1. A Memory named Coding
1. The only Memory your key can reach

**Tip:** to give each repository its own memory, create a Memory with the repository’s name.

## Step 2: Install the hooks

```bash
python3 01-coding-memory/install.py claude --key mbk_…   # Claude Code
python3 01-coding-memory/install.py codex  --key mbk_…   # Codex CLI
python3 01-coding-memory/install.py gemini --key mbk_…   # Gemini CLI
```

The installer uses only the Python standard library (3.9 or newer). What it does:

- Writes your key to **one shared file**, ~/.membase/config.env (mode 600). The key never goes into the CLI's own config.
- Backs up any config it changes as &lt;file>.membase-backup.
- Can be undone with --uninstall.

The hooks need the Membase Python SDK. If uv is installed, the first hook builds a cached environment in a few seconds and later hooks start immediately. Without uv, run pip install membase-ai.

**Prefer to install by hand?** For Claude Code:

```bash
claude plugin marketplace add ./01-coding-memory
claude plugin install membase-memory@membase-demos
```

To try it for one session only: claude --plugin-dir ./01-coding-memory/claude-plugin

## Step 3: Let the agent call memory itself (optional)

The hooks give you automatic recall and saving. To also let the agent search, add or forget memories when you ask, export your key so the MCP server can use it:

```bash
export MEMBASE_API_KEY=mbk_…   # add to your shell profile
```

Claude Code reads it in the plugin's .mcp.json. For Codex:

```bash
codex mcp add membase --url https://api.app.membase.com/mcp-http \
  --bearer-token-env-var MEMBASE_API_KEY
```

## Step 4: Verify that memory is working

Run the end-to-end check:

```bash
uv run 01-coding-memory/smoke.py
```

Then do the real test in your own project:

1. Decide something specific: a naming rule, or why you chose a library.
1. Quit the session.
1. Start a new session in the same repository.
1. Ask about it **without mentioning it**.

To watch what the hooks are doing, run tail -f ~/.membase/hooks.log in a second terminal.

## How the hooks work

![SessionEnd saves; SessionStart and UserPromptSubmit recall.](https://dmc2j1nsu0tnv.cloudfront.net/1792082278550-DWVc-membase-use-case-01-coding-agents-10.png)

SessionEnd saves; SessionStart and UserPromptSubmit recall.

![Table of hooks per CLI: Claude Code uses SessionStart, UserPromptSubmit and SessionEnd; Codex CLI uses SessionStart, UserPromptSubmit, Stop and SessionEnd; Gemini CLI uses SessionStart, BeforeAgent, AfterAgent and SessionEnd; all use MCP for search, add and forget. Tested on Claude Code v2.1.226 and Codex CLI v0.125.0; Gemini CLI not yet tested.](https://dmc2j1nsu0tnv.cloudfront.net/1792082284217-oZCy-membase-use-case-01-coding-agents-11.png)

A few design choices make it safe to leave on all day:

- **It never blocks you.** Any failure is written to ~/.membase/hooks.log, and the hook exits quietly.
- **Recall has a time budget.** Each prompt waits up to 10 seconds for memory (MEMBASE_RECALL_BUDGET). If the search takes longer, it keeps running, and its results arrive with your next prompt, marked as late. Nothing is lost and the search is never repeated.
- **One save per session.** The session is saved once, when it ends. Only user and assistant text is kept: tool calls, tool output, thinking, slash commands and system reminders are dropped. Each message is capped at 1,500 characters and the session at 12,000.
- **Saving runs in the background.** CLIs give end-of-session hooks very little time (Claude Code about 1.5 seconds), so the hook hands the save to a separate process. If it fails, it’s retried at the next session start.

## Common mistakes

![Table of common mistakes with symptom, cause and fix: Read-only key, no matching Memory, a slow first prompt while the hosted account wakes up, MEMBASE_API_KEY not exported, Windows not supported, and Gemini CLI not expanding $VAR in headers](https://dmc2j1nsu0tnv.cloudfront.net/1792082290395-VIZP-membase-use-case-01-coding-agents-12.png)

## More in this series

[**→ Browse all 17 Membase Use Cases**](https://github.com/membaseai/membase-use-cases#use-cases)

## Try it now

1. [**Star the repo**](https://github.com/membaseai/membase-use-cases): 17 runnable demos of what long-term memory makes possible.
1. [**Get a Membase developer key**](https://app.membase.com/) and run the installer.
1. Decide something, quit, and see if your next session remembers.

## Frequently Asked Questions

### Does this replace CLAUDE.md?

No. Keep stable conventions in CLAUDE.md. Membase catches the decisions you make while working, which you would otherwise have to write into that file yourself.

### Does the model have to decide to use memory?

No. Recall and saving run in hooks, outside the model. The MCP tools are an extra, for when you explicitly ask the agent to remember or forget something.

### What happens if Membase is slow or down?

Your session carries on normally. Recall waits at most 10 seconds by default, failures are only logged, and an unsaved session is retried at the next session start.

### What exactly gets saved?

Only the text of your messages and the agent’s replies. Tool calls, tool output, thinking, slash commands and system reminders are left out, and long messages are trimmed.

### Can each repository have its own memory?

Yes. Create a Memory with the repository’s folder name, or set MEMBASE_CONTAINER in that project's environment.

### Does it work with Codex CLI and Gemini CLI?

Codex CLI is tested (v0.125.0). Gemini CLI is wired the same way but hasn’t been tested yet. All three share one settings file, so a memory built in Claude Code is available in Codex too.

### Do I need to install anything besides Python?

Python 3.9+ for the installer, and the Membase SDK for the hooks (installed automatically with uv, or with pip install membase-ai).
