Memory & Persistence

Context windows are ephemeral — everything in them is lost when the session ends or context compacts. Memory and persistence strategies ensure critical information survives these boundaries.

The Persistence Hierarchy

Mechanism	Survives Compaction	Survives Session End	Shared with Team
Context window	No	No	No
Scratchpad files (NOTES.md)	Yes	Yes	If committed
.sdlc/ artifacts	Yes	Yes	Yes
Agent config files	Always loaded	Always loaded	Yes
Skills	Loaded on demand	Yes	Yes
Git commits	N/A	Yes	Yes
Per-user memory store	Yes	Yes	No

Scratchpad Files

For active work that spans compaction events, use scratchpad files:

Create PROGRESS.md to track this implementation.
After each completed step, update it with:
- What was done
- Files modified
- Test results
- Next steps

After any compaction, read PROGRESS.md to restore context.

When to use: Multi-step implementations, debugging sessions, any task longer than one context window.

Workflow Artifacts (.sdlc/)

For structured development workflows:

Research

.sdlc/research/auth-analysis.md

## Summary
The auth system uses JWT with Redis-backed refresh tokens.

## Key Files
- src/middleware/auth.ts — Token validation middleware
- src/services/auth.ts — Login, logout, refresh logic
- src/repos/sessions.ts — Redis session store

## Flow
1. Client sends JWT in Authorization header
2. auth.ts validates signature and expiration
3. If expired, checks refresh token in Redis
4. If valid refresh, issues new JWT
5. If invalid refresh, returns 401

Plans

.sdlc/plans/add-rate-limiting.md

## Steps
1. [x] Create rate limiter middleware (src/middleware/rateLimit.ts)
2. [x] Add Redis integration for distributed counting
3. [ ] Apply to auth endpoints with 100 req/min limit
4. [ ] Apply to API endpoints with custom limits
5. [ ] Add rate limit headers to all responses
6. [ ] Write integration tests

## Decisions
- Sliding window algorithm (not fixed)
- Fail-open when Redis is down
- Rate limit by API key, not IP

Specs

.sdlc/specs/rate-limiting.md

## Requirements
[Full specification — see Spec-Driven Development chapter]

The Three-Level Agent Configuration Hierarchy

Many AI coding agents support a layered configuration system that loads context at different scopes. The general pattern has three levels:

See the Tool Configuration Reference for the exact file names and locations your tool uses at each level.

Level 1: User-Global

Personal preferences that apply across all projects, stored in your tool’s global config file:

# Personal Preferences
- I prefer concise responses without trailing summaries
- Always use conventional commits
- Run tests before committing

Level 2: Project Root

Project-specific conventions shared with the team, stored in the root agent configuration file:

# MyProject
## Stack
TypeScript, Hono, Drizzle, Vitest, pnpm
## Commands
[project-specific commands]

Level 3: Directory-Specific

Domain-specific conventions loaded when working in a particular directory — stored in a configuration file within that subdirectory (e.g., src/api/):

# API Conventions
- All endpoints return { data, error, meta }
- Use zod for request validation
- Auth middleware applied via route groups

Session Continuity

Resuming Sessions

AI coding agents handle session continuity differently. Some support resuming via CLI flags; others maintain session state within their IDE panels. Check your tool’s documentation for session persistence options.

Naming Sessions

Some tools support named sessions. Named sessions are easier to find and resume. Treat sessions like branches — different workstreams get separate sessions.

Memory Best Practices

What to Persist Where

Information Type	Persist To	Why
Active task progress	PROGRESS.md or NOTES.md	Survives compaction, easy to update
Research findings	.sdlc/research/	Reusable across sessions
Implementation plans	.sdlc/plans/	Survive compaction, reviewable
Architectural decisions	Git commit messages	Permanent, searchable history
Project conventions	Agent config file	Loaded every session
Domain knowledge	Skills / snippets directory	On-demand, doesn’t bloat every session
Personal preferences	User-global agent config	Global, personal

Compaction-Aware Prompting

Add instructions to your agent configuration file:

## Compaction Instructions
When compacting, always preserve:
- The full list of modified files
- All test commands that have been run
- Current plan progress and next steps
- Any architectural decisions made this session
- Active NOTES.md or PROGRESS.md file references

Tip

For long-running workflows, use BOTH compaction and persistence tools: compaction keeps the active context manageable, and file-based memory persists information across compaction boundaries so nothing critical is lost in the summary.