plans/hackathon/01-what-is-claude-mem-field-guide.md
A no-code, no-jargon explanation of what Claude-Mem is, why it exists, and how it works — written for hackathon builders who have never seen it before.
Claude-Mem gives your AI coding agent a memory. A second agent sits next to your main agent, watches everything it does, writes down the parts worth remembering, and hands those notes back the next time you start working — so your agent wakes up already knowing what happened yesterday.
That's it. Everything else in this guide is detail.
Imagine hiring a brilliant engineer. Incredibly fast, knows every language, never gets tired. There's one catch: every morning they arrive with total amnesia. They don't remember the codebase, the bug you fixed together yesterday, the decision you made about the database last week, or the three approaches that already failed.
So every morning starts the same way. They re-read the files. They re-discover the structure. They re-ask the questions you already answered. They sometimes re-try the thing you already proved doesn't work. The first ten or twenty minutes of every single session is spent just getting back to where you were.
That is exactly what working with an AI coding agent feels like today. The agent is brilliant inside a session and a blank slate the moment the session ends.
This has three real costs:
Claude-Mem exists to fix all three.
Here's the core insight, and it's a simple one.
You don't need to make the main agent remember. You just need someone to take notes while it works, and to hand those notes back at the right moment.
So Claude-Mem adds a second agent. Call it the observer. It doesn't write code. It doesn't talk to you. It has exactly one job: watch the main agent work, and keep a running notebook of what's worth remembering.
Think of it like a scribe in the room. Your main agent is the builder — reading files, editing code, running commands, making decisions. The observer is sitting in the corner with a notebook. Every time the builder does something, the observer glances over and asks one question:
"Is this worth writing down?"
Most of the time the answer is no. Reading a file to check something trivial? No note. Running a quick command that showed nothing interesting? No note. The observer is deliberately selective — a notebook full of trivia is as useless as no notebook at all.
But when the answer is yes — a bug got fixed, a decision got made, something surprising was discovered, a feature shipped — the observer writes a note. A proper, structured note, not a dump of raw text.
And then the next time you sit down to work, the observer opens the notebook and says: "Here's what happened recently. Here's what you were in the middle of. Here's what you decided and why." The builder reads the notes and starts warm.
That is Claude-Mem. Two agents: one does the work, one remembers it.
This is the "how does it actually plug in?" question, and the answer is simpler than you'd expect.
When an AI coding agent works, it doesn't do magic — it takes actions. It reads a file. It edits a file. It runs a command. It searches for something. Each of these is called a tool use. A session is really just a long sequence of tool uses.
Claude-Mem hooks into the moments around those actions. The agent's environment (Claude Code, and others) lets outside programs listen for a handful of lifecycle moments:
The important thing: Claude-Mem never interrupts or changes what the main agent does. It watches from the outside. If Claude-Mem crashed entirely, the main agent would carry on exactly as before — it just wouldn't remember anything afterward. The main agent is never slowed down waiting for the observer; the note-taking happens in the background.
So the picture looks like this:
Your main agent The observer agent
(does the work) (takes the notes)
───────────────── ───────────────────
reads a file ──► handed over ──► "worth a note? ...no."
edits a file ──► handed over ──► "worth a note? ...no."
runs the tests ──► handed over ──► "worth a note? YES — tests went green
after the config fix." ✎ writes note
fixes a bug ──► handed over ──► "worth a note? YES." ✎ writes note
...
session ends ──► handed over ──► writes a short summary of the session
Every tool use goes to the observer. The observer decides which ones become notes.
The observer doesn't write a diary. It writes structured notes — and the structure is what makes them useful later, because structure is what makes notes searchable, skimmable, and cheap to hand back.
Every note (Claude-Mem calls them observations) has the same shape:
One line. What happened, written so that the title alone tells you whether you care. Example: "Fixed login redirect loop caused by stale session cookie." The title is the most important field, because most of the time the title is all the future agent will read.
One more line of context. What part of the system, what the situation was.
Three-ish single-sentence bullet points. Each one is a standalone, true statement that makes sense on its own with no surrounding context. These are the "semantic chunks" — small, self-contained pieces of meaning that can be found by search and understood in isolation. Examples:
Each fact is one sentence. Each fact could be pulled out and dropped into a totally different conversation and still be useful. That is the test.
A short paragraph telling the story: what was happening, what was tried, what was learned, why it matters. This is the "for when you need the full picture" field. The facts are for skimming; the narrative is for understanding.
One label from a fixed list, so the notebook can be filtered and color-coded. In the default code mode the categories are things like:
(Plus a few security-related ones.) The category answers "what kind of thing is this?" at a glance.
A handful of reusable labels describing what kind of knowledge is in the note, independent of the specific topic. In code mode these are things like how-it-works, why-it-exists, what-changed, problem-solution, gotcha, pattern, trade-off. Tags are what let you later ask "show me every gotcha we've hit in this project."
Which files were read, which were changed. This lets the future agent jump straight to the right place.
Every note knows exactly when it happened, which is what makes the timeline possible — you can look at any note and ask "what happened right before and after this?"
Put together, one note looks roughly like this (in plain English, not the real format):
bugfix · 3:48 PM Fixed login redirect loop caused by stale session cookie Auth middleware in the web app
- The redirect loop only happened when the session cookie was older than 24 hours.
- The fix clears the cookie before re-issuing the login redirect.
- The logic lives in the auth middleware, not the login page.
Users reported getting bounced between /login and /dashboard forever. Tracing it showed the middleware was trusting a cookie that the server had already expired. Clearing it before redirecting broke the loop. Worth remembering because the symptom looks like a frontend routing bug but the cause is server-side.
tags: problem-solution, gotcha · files: middleware/auth.ts
Title, facts, narrative, category, tags, files, time. Every note. Same shape. That consistency is the whole trick.
On your machine. Claude-Mem stores every observation in a local database in your home folder (~/.claude-mem), alongside a search index that understands meaning — not just exact words — so you can search for "that cookie thing" and find the redirect-loop note. Nothing leaves your machine except the calls to the AI model doing the observing. (There's an optional Pro tier with cloud sync if you want the same memory across machines — it's optional.)
This is the part that makes Claude-Mem practical rather than just nice. If it handed the agent every note in full at the start of every session, it would blow the budget instantly. Instead it uses layers, cheapest first:
Layer 1 — The timeline (automatic, every session). When a session starts, Claude-Mem injects a compact list: ID, time, category icon, title. Just titles. Fifty recent notes might cost a few hundred tokens. The agent skims the titles and usually that's enough — "oh right, we fixed the cookie thing yesterday."
Layer 2 — Fetch by ID (on demand). If a title looks relevant and the agent wants the details, it asks for that specific note by its ID and gets the facts, narrative, and files. Only pays for what it actually needs.
Layer 3 — Search (when it's not in the timeline). For anything older, or on a different topic, the agent can search the whole history — by meaning, by keyword, by category, by date, by project. Search returns titles first; the agent filters, then fetches details for the interesting ones. Same cheap-first discipline.
This "titles first, details on demand" pattern is why the startup context you see from Claude-Mem says things like "50 observations, 17,530 tokens to read, 1.3 million tokens of work behind them, 99% savings." The notes are a compressed index of a huge amount of work, and the agent only unpacks the parts it needs.
There's also a little local web page where you, the human, can watch the notes land in real time as your agent works, browse by project, and search. It's the easiest way to see memory happening.
So far, everything above has assumed the observer is watching a coding session. That's the default. But here's the part that opens up the most creative room:
The observer's job description is swappable.
Claude-Mem calls a job description a mode. A mode is a plain configuration file that defines four things:
That's all a mode is. Swap the mode, and the same machinery — the same second agent, the same watch-every-action loop, the same title/facts/narrative/category/tags note shape — now observes something completely different.
Because the observer just watches "actions and their results," and actions can be anything the agent does, the thing being observed does not have to be code:
Modes that already exist in the repo and in the wild include code (default), a calmer code variant that only records things painful to rediscover, email investigation, law study, meme-token trading signals, and a robot-monitoring mode — which gives you a sense of the range.
And you don't have to hand-write one. There's a /mode-creator skill that interviews you — what are you observing, what kinds of things matter, what should the categories be — and writes, installs, and activates the mode for you.
Any data in, any pattern out. Pick what to watch. Tell the observer what matters. Get structured, timestamped, searchable notes.
Because all the pieces are simple and exposed, they make good building blocks:
AI agents are about to do a lot of the world's work. Right now, every one of them wakes up with amnesia. Whatever fixes that is going to matter a lot.
Claude-Mem's bet is that the fix isn't one giant model that somehow remembers everything. The fix is boring and robust: a second agent, a notebook, a consistent note shape, and a cheap-first way of handing notes back. It's the kind of thing that works today, costs very little, and composes with everything else.
Over 100,000 developers already use it. It's open source. And the pieces are small enough that one person, in one weekend, can build something genuinely new on top of them.
npx claude-mem install/mode-creator and point the observer at something that isn't code.Every hacker gets 30 days of CMEM Pro free: install, then use code FASTHACK30 at cmem.ai.
Repo and skills: github.com/thedotmack/claude-mem
Sponsored by Claude-Mem. Judged separately from overall 1st–3rd, so you can win both.
The challenge: build an agentic tool that actually remembers.
Seven directions — pick one, combine a few, or bring your own:
And finally: everything scores extra for being something someone would actually use.