Claude Code Memory: Audit What Survives the Session

Audit Claude Code memory with a tested read-only Python script. Check saved preferences, missing notes and index limits before the next team handoff.

A memory folder diagram with MEMORY.md as the index and feedback.md as a topic note to review for scope, beside the words Claude Code memory audit.

Claude Code memory carries information between sessions through the instructions you maintain and the notes Claude saves for itself. Start a memory review with /memory: open the auto-memory folder, inspect MEMORY.md and its linked notes, and check whether an old preference still fits the next task. A remembered shortcut needs an explicit scope, especially when several people or agents work on the same repository.

This guide covers the native system first, then a read-only Python auditor we tested against 12 synthetic memory folders. The auditor finds structural problems and phrases worth reviewing. It leaves your files unchanged and makes no model calls. Its results include an intentional false positive and false negative, because text matching cannot decide whether a future action is authorized.

What survives a Claude Code session?

Claude Code has authored instruction files and native auto memory. Auto memory uses a machine-local folder for each repository, shared across its worktrees, with MEMORY.md as an index and separate topic notes. The index has a startup limit of 200 lines or 25KB, whichever comes first; topic files are read on demand. These details come from the current memory documentation, checked November 9, 2026.

Keep four things separate when deciding where information belongs:

Information Example Place to review it Review question
Shared project instructions The command required before merging Checked-in project instruction file Does every developer agree this is still the workflow?
A remembered preference You prefer a short explanation before a large change Auto-memory note Was this a lasting preference or a request for one task?
Active task evidence The current failing test output Current session and task record Can the next worker reproduce it from the current checkout?
A third-party memory service Searchable historical tool observations That service's configuration and storage What is collected, where does it go, and who can retrieve it?

Our CLAUDE.md best practices guide covers the first row in detail. Here, the useful question is what Claude wrote down after working with you, and what that note might mean in a different situation.

For example, a developer might permit automatic formatting of generated documentation. Later, another worker opens a payment-service change. A broad note saying “skip confirmation for routine edits” leaves the next session to guess whether those two jobs have the same risk. A scoped note names the documentation task and preserves the payment-service checkpoint.

That example is hypothetical. It illustrates the review decision; it is not a claim that we observed a production incident.

Why a harmless preference can become an unsafe memory

The November 5 preprint The Memory Trap studies overgeneralization from benign interactions. Its experiments compare later behavior with and without memory. Low-stakes requests to skip confirmation can carry into simulated high-stakes work; legitimate test repairs can also become a broader tendency to weaken tests. The authors distinguish overgeneralization when writing a memory from overgeneralization when using it.

These are constructed evaluations, mostly from one model family, with relatively short autonomy scenarios. They do not establish the failure rate of your repository or prove that a particular Claude Code deployment will behave the same way. They do give a concrete reason to review the scope of saved feedback.

Use three questions when reading a note:

  1. What did the person approve at the time?
  2. What conditions made that approval reasonable?
  3. What must be checked again before applying it elsewhere?

A note that answers only the first question can become misleading once the conditions change. Recording the original context helps the next worker understand why the decision existed.

Inspect the memory folder before changing anything

Run /memory in the Claude Code session you use for the repository. Open the auto-memory folder it identifies. Use that observed location rather than guessing a directory name from a different machine. Read the index, then open the notes relevant to the work you are about to assign.

For this review, group the notes into four practical buckets: preferences, historical decisions, pointers to evidence, and statements that sound like authorization. This is a review technique, not a required Claude file schema. A note can belong in more than one bucket.

Prioritize statements involving production, credentials, payment changes, deleting files, weakening tests, or avoiding checkpoints. Keep harmless style preferences in proportion: “prefer short paragraphs” needs less scrutiny than “approve all future deployment steps.”

Read the whole note around a suspicious phrase. “Never bypass permission checks” contains the same words as an instruction to bypass them. An automated flag should send you to the surrounding explanation, not trigger a deletion.

Also check the operational facts. A stored command may refer to a script that moved, and an internal-document pointer may have lost access. Run the current documented verification step before using that remembered information to guide a change. A note is a starting point for finding evidence.

Run a read-only audit of one chosen folder

Save the following script as memory_audit.py. It uses the Python standard library and was executed with Python 3.14 in our fixture run. It expects UTF-8 Markdown and simple Markdown links in the index. It reports filenames and hashes without including the note text in its JSON output.

Pass only the folder you intend to inspect. The script checks resolved file paths before reading a note and reports references outside that root. It does not inspect settings precedence, parse every Markdown-link syntax, or emulate Claude's retrieval decisions. Avoid running it while another process is changing the folder: the checks are not a security boundary against concurrent filesystem changes.

"""Read-only triage for a chosen Claude Code memory folder. No network calls."""
import argparse
import hashlib
import json
import re
from pathlib import Path

RISK = re.compile(r"skip.{0,30}confirm|don.t ask|always approve|bypass.{0,30}permission", re.I)
LINK = re.compile(r"\[[^\]]*\]\(([^)]+)\)")

def audit(folder):
    root = Path(folder).resolve()
    findings, files = [], []
    def note(code, path, line=None):
        findings.append({"code": code, "file": str(path), "line": line})
    def read(path):
        resolved = path.resolve()
        if not resolved.is_relative_to(root):
            note("outside_memory_root", path.name)
            return None
        if not path.is_file():
            note("missing_file", path.name)
            return None
        raw = path.read_bytes()
        files.append({"file": str(path.relative_to(root)), "sha256": hashlib.sha256(raw).hexdigest()})
        return raw.decode("utf-8")
    index = read(root / "MEMORY.md")
    if index is None:
        return {"files": files, "findings": findings, "startup_lines": None}
    lines = index.splitlines(keepends=True)
    used, startup = 0, []
    for line in lines[:200]:
        room = 25000 - used
        if room <= 0:
            break
        chunk = line.encode("utf-8")[:room]
        startup.append(chunk.decode("utf-8", errors="ignore"))
        used += len(chunk)
    # Preview uses a conservative decimal 25KB; this is not Claude's loader.
    if len(lines) > 200:
        note("index_over_200_lines", "MEMORY.md")
    if len(index.encode("utf-8")) > 25000:
        note("index_over_25kb", "MEMORY.md")
    for path, text in [(root / "MEMORY.md", index)] + [
        (p, read(p)) for p in sorted(root.rglob("*.md")) if p != root / "MEMORY.md"
    ]:
        if text is None:
            continue
        for number, line in enumerate(text.splitlines(), 1):
            if RISK.search(line):
                note("review_authorization_language", path.relative_to(root), number)
    for target in LINK.findall(index):
        if "://" in target or target.startswith("#"):
            continue
        candidate = root / target.split("#", 1)[0]
        if not candidate.resolve().is_relative_to(root):
            note("outside_memory_root", target)
        elif not candidate.is_file():
            note("missing_index_target", target)
    return {"files": files, "findings": findings, "startup_lines": len(startup),
            "startup_preview_bytes": used}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("memory_folder")
    args = parser.parse_args()
    print(json.dumps(audit(args.memory_folder), indent=2, default=str))

Run it with the path you opened through /memory. This example uses a local demonstration folder, so it can be reproduced without reading any personal memory:

mkdir -p memory-demo
printf '[Review note](feedback.md)\n' > memory-demo/MEMORY.md
printf 'Skip confirmation for every change.\n' > memory-demo/feedback.md
python3 memory_audit.py memory-demo

The report includes review_authorization_language for feedback.md, along with the hashes of the two input files. We ran this exact example during validation. The phrase is deliberately broad; deciding how to replace it requires the original task context.

The startup preview uses a conservative decimal 25,000-byte ceiling. It helps identify an oversized index; it is not a byte-for-byte implementation of Claude's loader. The official documentation describes the limit as 25KB. The script does not truncate or repair your index.

What the 12 fixture cases actually tested

We built isolated folders for the following cases and compared input-file hashes before and after every audit:

Fixture group Cases Observed result
Empty folder, valid linked note, missing linked note 3 Missing inputs were reported; the valid pair produced no findings
Parent traversal, absolute reference, symlink outside the root 3 Each outside-root reference was flagged
Index at 201 lines, oversized ASCII, oversized multibyte text 3 The applicable line or byte warning appeared
Broad approval phrase 1 The phrase was flagged for review
A warning against bypassing permissions 1 It was flagged too, demonstrating a false positive
Equivalent authorization phrased differently 1 It was missed, demonstrating a false negative

All 12 cases matched their expected results, and the input-file hashes were unchanged. These are deterministic file-processing checks. They do not measure recall quality, prompt-injection resistance, model behavior, or the likelihood of a production failure.

Two examples explain why the tool must stay a triage aid. It flags “Never bypass permission checks,” which is a sensible warning. It misses “Ship all future changes without a checkpoint,” which deserves scrutiny. Adding more regular expressions moves those boundaries; it cannot turn the report into a reliable authorization decision.

Rewrite broad feedback with the original scope

When a note is too broad, preserve the reason it was written and describe the task where it applies. Here is an illustrative rewrite for the documentation example:

Original task: Reformat generated API reference pages in this repository.
Preference: Apply the formatter without a separate formatting-only checkpoint.
Scope: Generated documentation with no behavioral changes.
Recheck: Any code, configuration, deployment or security-sensitive change.
Evidence: The reviewed task record and the current formatter command.

This is a human review template, not a Claude configuration format or an enforcement mechanism. The fields help a reviewer distinguish a formatting preference from permission to change a service. They do not grant that permission.

For a historical exception, add an absolute date and identify who will revisit it. For example, a temporary freeze should name its end date and the affected component. A review date written into a note is a reminder for your process; it does not make native auto memory expire automatically.

Keep shared, durable decisions in the place your team already reviews. If a note reveals a project-wide build requirement, propose a change to the checked-in instructions rather than assuming everyone has the same private memory. If it explains a one-off investigation, keep a pointer to the task evidence and enough context to understand its limits.

Before transferring a preference to another worker, ask that worker to restate the relevant scope and verification step. Then review the proposed action through your normal controls. This catches ambiguity while the work is still small enough to inspect.

Troubleshoot missing or stale memories

When Claude appears to forget a note, first distinguish storage from use. Check that the note exists in the folder for this repository, that its index entry still points to the correct file, and that the important index entry is within the documented startup limits. A file existing on disk does not prove it was read for the current task.

If the loss followed /compact, check the session summary as well as saved memory. Our Claude Code compact guide shows how to preserve decisions, open questions and verification state before compaction and test what survived afterward.

The auditor checks simple local Markdown links. If your index uses plain filenames, unusual escaping, or prose descriptions, inspect those references manually. Likewise, an unflagged sentence can still be stale or wrong. Read the notes most relevant to the next change even when the report is empty.

If a remembered decision conflicts with the current repository, investigate the change that made it stale. Updating the note alone may leave an old instruction in a second location. Record which source now governs the workflow, then review the other copies. Our team settings guide explains how to inspect the settings used by a session.

You can pause native auto memory while investigating. The current docs describe an /memory toggle, autoMemoryEnabled: false in project settings, and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Turning it off does not clean up old notes or remove authored instruction files. Make the operational choice explicit, and review saved notes before relying on them again.

Keep memory review connected to team coordination

A remembered explanation can help a worker find the right starting point. Team coordination still needs a current record of who owns the task and which files are being changed. Otherwise, two sessions can have useful context and still edit the same component at once.

For mixed-tool teams, review the proposed change and the current task record together. Keep the sensitive action behind Claude Code permissions or the relevant external control. Use hooks for checks that must run at a particular tool event. A well-written memory note helps explain the workflow; the enforcement lives in the configured control.

SYNCStaff supports this team workflow with shared task boards, intents, file leases and conflict arbitration, with a human in the loop. When a memory review changes the scope of a task, record that scope on the shared board before another agent takes it. Check the current file ownership before editing. That makes the review useful beyond the session that discovered the problem.

Start with one note that influences an important action. Find its original context, verify the current evidence, and narrow its wording where necessary. Then give the next worker a concrete task and a visible checkpoint. That is a review your team can repeat when tools, models or project assumptions change.

Frequently asked questions

Where is Claude Code memory stored?

Use /memory in your current session to open the repository memory folder. Native auto memory is stored locally on the machine, with MEMORY.md as an index and separate topic files. Review the location your session actually uses before copying, editing or auditing notes from another workspace.

How is auto memory different from CLAUDE.md?

CLAUDE.md holds instructions you maintain for the project or your own workflow. Auto memory holds notes Claude saves for future sessions. Review shared rules through the team’s normal change process, and check saved feedback for its original scope before treating it as guidance for a different task.

Do Git worktrees share Claude Code memory?

The current native-memory documentation says worktrees and subdirectories within the same Git repository share a memory directory on that machine. Separate worktrees therefore do not imply separate remembered preferences. Inspect the location through /memory, and review sensitive notes before assigning work with a different scope.

Can a saved memory approve future agent actions?

A saved note can explain a previous decision, but a reviewer still needs to establish whether that decision applies to the current action. Record the original task, its limits and the evidence to recheck. Keep sensitive actions behind the permissions, hooks or external controls your team has configured.

Does the Python auditor prove a memory folder is safe?

No. It checks file structure and a few phrases, and the fixture run deliberately demonstrates both a false positive and a missed paraphrase. An empty report does not prove correct scope or safe model behavior. Read relevant notes and verify their evidence before the next important change.