code-memory

Code Memory

Persist understanding of code structure and implementation details gained during investigations so future sessions can ramp up quickly without re-reading source files.

When to Use

• After investigating source code and gaining understanding of how classes/modules work
• Before investigating code, to check if prior context exists that provides a shortcut
• When asked to "remember" or "save" understanding of code
• During any investigation that reads multiple source files to understand a subsystem
• When switching to a new session that may need the same code understanding

When Not to Use

• For storing user preferences or project-wide conventions (use CLAUDE.md or copilot-instructions.md)
• For tracking todos or work items (use session SQL)
• For files outside the current repository

Inputs

Workflow

Step 1: Determine the memory file path

Map the source file path to a memory file path. The memory file mirrors the source path structure inside the memory/ directory within this skill's folder.

Path mapping rule:

• Take the source file path relative to the repository root
• Replace path separators with / for consistency
• Append .md extension
• Prefix with the memory directory path

Example mappings (repository root: D:\git\CoreWCF):

The memory directory base path is: .copilot/skills/code-memory/memory/

Step 2: Check for existing context (Load phase)

Before reading a source file during an investigation:

1. Check if a memory file exists for the source path
2. If it exists, check timestamps:
   • Get the last-modified time of the source file
   • Get the last-modified time of the memory file
   • If the source file is newer than the memory file, flag the context as potentially stale
3. If the memory file exists and is not stale:
   • Read and summarize the memory file
   • Decide if it contains sufficient information for the current investigation
   • If sufficient, use the cached context instead of reading the source file
   • If insufficient, proceed to read the source file (and update context afterward in Step 4)
4. If the memory file exists but is stale:
   • Read the memory file for baseline understanding
   • Read the source file to validate and identify changes
   • Proceed to Step 4 to update the context
5. If no memory file exists, read the source file and proceed to Step 3/4

Step 3: Investigate the source code

Read and understand the source file(s). Focus on capturing:

• Class/interface purpose — What role does this play in the system?
• Key public API — Important methods, properties, and their contracts
• Internal structure — How the class organizes its work (key private methods, state management)
• Dependencies — What other classes/services does it depend on? How are they injected?
• Design patterns — Observer, strategy, factory, etc. if applicable
• Threading/async model — Concurrency considerations, locks, async flows
• Extension points — Virtual methods, events, delegates, interfaces for customization
• Non-obvious behavior — Gotchas, edge cases, implicit assumptions, ordering requirements
• Relationships — How this class connects to its callers and callees in the broader system

Step 4: Write or update the memory file (Save phase)

Create or update the memory file with the gained understanding.

Memory file format:

# {ClassName} — {Brief one-line purpose}

**Source:** `{relative/path/to/source.cs}`
**Namespace:** `{Namespace}`
**Last validated:** {YYYY-MM-DD}

## Purpose

{1-3 sentences describing what this class does and why it exists}

## Key API

{List the important public methods/properties with brief descriptions of what they do,
their parameters, and return values. Focus on what callers need to know.}

## Internal Structure

{Describe how the class works internally. Key fields, state management,
the flow of important operations. This is the "how" that saves future readers
from having to trace through the code.}

## Dependencies

{What does this class depend on? DI-injected services, static helpers, base classes.
Note how dependencies are obtained and used.}

## Design Notes

{Patterns used, threading model, non-obvious behavior, gotchas, important
invariants that must be maintained. Only include if there's something
worth noting.}

## Relationships

{How does this class fit into the broader system? What calls it?
What does it call? Key interaction flows.}

Writing guidelines:

• Write for copilot needing to understand this code as part of an investigation without reading it
• Be specific — include actual method names, field names, parameter types
• Focus on "why" and "how" over "what" (the source code already shows "what")
• Omit sections that have nothing noteworthy to say
• Keep each file under 200 lines — this is a summary, not documentation
• Use code snippets sparingly, only for key patterns that are hard to describe in prose

When updating an existing memory file:

• Preserve existing content that is still accurate
• Add new sections or details learned in the current investigation
• Update the "Last validated" date
• If the source file changed, revise any descriptions that no longer match

Step 5: Create parent directories as needed

Before writing the memory file, ensure all parent directories in the memory path exist.

New-Item -ItemType Directory -Path "{parent_directory}" -Force

Validation

After saving context:

• The memory file exists at the expected path
• The memory file contains the required header fields (Source, Namespace, Last validated)
• The content accurately reflects the source code as currently understood
• The file is under 200 lines

After loading context:

• The memory file was found (or confirmed not to exist)
• Staleness was checked via timestamp comparison
• The loaded context was evaluated for sufficiency before deciding to read source

Common Pitfalls