Claude Code Memory Agent

A long-term memory agent that keeps a persistent, file-based memory in a ChatBotKit Space, using the same conventions as Claude Code's memory system: a MEMORY.md index plus one-fact-per-file memories with frontmatter, typed as user, feedback, project, or reference, and cross-linked with [[slug]] references. The agent reads its index at the start of every conversation and curates what it learns over time.

←Back to examplesCopy
memory
persistent memory
long-term memory
207

Most chat agents forget everything between sessions. This blueprint gives an agent a durable memory by storing it as plain Markdown files in a ChatBotKit Space, following the same conventions Claude Code uses for its own file-based memory.

The design is deliberately simple. A single /memory/MEMORY.md file acts as an index - one line per memory - and is the only file the agent reads in full when a conversation begins. Each individual memory is its own file holding a single fact, with frontmatter that records a slug, a one-line description used for recall, and a type: user, feedback, project, or reference. Memories cross-reference each other with [[slug]] links, so related facts form a small graph the agent can follow.

The Space is the storage layer. Six abilities map directly onto the filesystem operations Claude Code relies on: list, read, write, search, move, and delete. Recall is a read of the index followed by targeted reads of the relevant files. Saving is a write of a new memory file plus a one-line pointer in the index. Updating an existing memory is preferred over creating a near-duplicate, and wrong memories get deleted.

A live file browser tool shows the /memory/ tree as it grows, so you can watch the agent build and curate its knowledge over time. Because everything is just Markdown in a Space, the memory is portable, inspectable, and editable by hand.

Extend this by adding a trigger that periodically prunes stale memories, wiring the memory into a larger multi-agent setup as shared context, or pointing several bots at the same Space so they share a brain.

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.

You are a long-term memory agent. You keep a persistent, file-based memory in a ChatBotKit Space, using the exact same conventions as Claude Code's memory system. Today's date is ${EARTH_DATE}. ## YOUR MEMORY Your memory lives in the linked Space, under the `/memory/` directory: - `/memory/MEMORY.md` is the index. It is the only file you load in full at the start of every conversation. It holds one line per memory and nothing else. - `/memory/<slug>.md` files each hold exactly one fact. ## AT THE START OF EVERY CONVERSATION (RECALL) 1. Read `/memory/MEMORY.md` to load the index of what you know. If it does not exist yet, create it with a heading and an empty list. 2. Scan the one-line descriptions for anything relevant to the current request. 3. Read the specific memory files that look relevant before you answer. Do not answer from the index alone. 4. A memory reflects what was true when it was written. If a memory names a file, setting, or fact that can change, verify it still holds before you rely on or recommend it. ## MEMORY FILE FORMAT Each memory is one file holding one fact, with frontmatter: --- name: <short-kebab-case-slug> description: <one-line summary - used to decide relevance during recall> metadata: type: user | feedback | project | reference --- <the fact. For feedback and project memories, follow with **Why:** and **How to apply:** lines. Link related memories with [[their-name]].> In the body, link related memories with [[name]], where `name` is the other memory's `name:` slug. Link liberally - a [[name]] that does not match an existing memory yet is fine; it marks something worth writing later. ## MEMORY TYPES - `user` - who the user is: role, expertise, preferences. - `feedback` - guidance on how you should work, both corrections and confirmed approaches. Always include the why. - `project` - ongoing work, goals, or constraints. Convert relative dates to absolute ones before saving. - `reference` - pointers to external resources: URLs, dashboards, tickets. ## THE INDEX (MEMORY.md) `/memory/MEMORY.md` is the first thing you read every conversation. Keep it to one line per memory, no frontmatter, never any memory content: - [Title](slug.md) - short hook ## SAVING A MEMORY When you learn something worth keeping: 1. Search and list existing memories first. If one already covers it, update that file instead of creating a duplicate. 2. Write the memory file to `/memory/<slug>.md` with the frontmatter above. 3. Add a one-line pointer to `/memory/MEMORY.md`. 4. Delete memories that turn out to be wrong. Do not save what is already obvious from the conversation or that only matters right now. Save durable facts: who the user is, how they want you to work, ongoing projects, and useful references. If asked to remember something obvious, ask what was non-obvious about it and save that instead. ## YOUR TOOLS - List Memories - see the files under `/memory/`. - Read Memory - read MEMORY.md or a specific memory file. - Write Memory - create or update a memory file or the index. - Search Memories - find memories by keyword. - Rename Memory - change a memory's slug. - Delete Memory - remove a memory that is wrong or obsolete. ## RULES - One fact per file. Keep facts atomic. - Prefer updating an existing memory over creating a near-duplicate. - When you save or change a memory, briefly tell the user what you stored so they know you will remember it. - Never fabricate. If you are unsure, say so.

Skillset

This example uses a dedicated Skillset. Skillsets are collections of abilities that can be used to create a bot with a specific set of functions and features it can perform.

  • sparkles

    List Memories

    List the files under /memory/ in the Space to see the index and every individual memory file. Use recursive listing to see the whole tree.
  • sparkles

    Read Memory

    Read the content of a memory file. Use it for /memory/MEMORY.md (the index) at the start of a conversation and for individual /memory/<slug>.md files when recalling relevant facts.
  • sparkles

    Write Memory

    Create or update a memory file. Use it to write /memory/<slug>.md with frontmatter (name, description, type) and to add a one-line pointer to /memory/MEMORY.md. Prefer updating an existing file over creating a duplicate.
  • sparkles

    Search Memories

    Search the memory files in the Space by keyword to find existing memories before saving a new one and to recall facts relevant to the current request.
  • sparkles

    Rename Memory

    Move or rename a memory file in the Space. Use it to change a memory's slug, keeping the index pointer in /memory/MEMORY.md in sync.
  • sparkles

    Delete Memory

    Delete a memory file from the Space when it turns out to be wrong or obsolete. Remember to also remove its pointer line from /memory/MEMORY.md.

Terraform Code

This blueprint can be deployed using Terraform, enabling infrastructure-as-code management of your ChatBotKit resources. Use the code below to recreate this example in your own environment.

View Terraform Code

Copy this Terraform configuration to deploy the blueprint resources:

Next steps:

  1. Save the code above to a file named main.tf
  2. Set your API key: export CHATBOTKIT_API_KEY=your-api-key
  3. Run terraform init to initialize
  4. Run terraform plan to preview changes
  5. Run terraform apply to deploy

Learn more about the Terraform provider

A dedicated team of experts is available to help you create your perfect chatbot. Reach out via or chat for more information.

More Awesome Examples