Skip to content

Agentic Session History

Jump to bottom
Steve edited this page Jul 23, 2026 · 1 revision

Agentic Session History: Setup Prompt & Workflow

A reusable prompt and convention for giving AI coding agents persistent memory across sessions by logging all interactions, changes, and commands to an agentic_history folder in your repository.

Why This Exists

Agentic coding tools (Replit Agent, Cursor, Claude Code, Copilot Workspace, etc.) are powerful, but each new session typically starts with a blank slate. The agent doesn't remember:

  • What was built in previous sessions
  • Why architectural decisions were made
  • What commands were run and which ones failed
  • What was left unfinished

This convention solves that by treating the repository itself as the agent's memory. Every session reads the history on startup and writes to it as work happens — creating a continuous feedback loop across sessions, developers, and even different AI tools.

Benefits

Benefit Description
Continuity New sessions pick up exactly where the last one left off
Auditability Every file change, command, and decision has a timestamped record
Team visibility Any developer can review what the agent did and why
Tool portability The history is plain Markdown — any agent or human can read it
Debugging Failed commands and errors are logged, making regressions traceable

Folder Structure

agentic_history/
├── session_2026-07-23_0930.md   # Per-session log (prompts, reasoning, actions)
├── session_2026-07-24_1415.md
├── changes.md                    # Running log of all file changes with diffs
├── commands.md                   # All shell commands / tool calls + outcomes
└── summary_2026-07-23.md        # End-of-session summaries for future context

The Prompt

Paste this at the start of every agentic session:

For this entire session, you must maintain a complete audit trail of your work in a folder called agentic_history at the project root. Create the folder if it doesn't exist. Follow these rules without exception:

  1. Load prior context first: At the very start of the session, before doing any other work, read the contents of the agentic_history folder — including past session logs, changes.md, commands.md, and any summary files. Use this history to build context about the project's state, prior decisions, known issues, and suggested next steps, and briefly summarize back to me what you learned from the history before we begin. If the folder is empty or missing, note that this is a fresh project and create the folder.

  2. Session log: Create agentic_history/session_<YYYY-MM-DD_HHMM>.md with a header noting the date, my initial request, relevant context carried over from prior sessions, and your planned approach. Append to this file throughout the session.

  3. Log every interaction: For each of my prompts and each of your responses, append an entry to the session log containing: a timestamp, my request (verbatim), a summary of your reasoning, and the actions you took.

  4. Log every change: Before modifying, creating, or deleting any file, record an entry in agentic_history/changes.md with: the timestamp, file path, type of change (create/edit/delete), the reason for the change, and a before/after diff or snippet of the modified code.

  5. Log commands and tools: Record every shell command, package installation, and tool invocation you execute in agentic_history/commands.md, along with its output status (success/failure) and any errors encountered.

  6. Session summary: Before ending the session or when I say "wrap up," write agentic_history/summary_<date>.md listing all files changed, features completed, known issues, and suggested next steps written so a future session can pick up exactly where this one left off.

Never skip logging, even for small changes. If a task would proceed without being logged, stop and log it first. Confirm you understand these rules, load the existing history, summarize the project context, then wait for my first task.

Session Lifecycle

┌─────────────────────────────────────────────────────┐
│ 1. SESSION START                                    │
│    Agent reads agentic_history/ → summarizes        │
│    project state, prior decisions, open items       │
├─────────────────────────────────────────────────────┤
│ 2. DURING THE SESSION                               │
│    Every prompt/response  → session_<date>.md       │
│    Every file change      → changes.md              │
│    Every command/tool run → commands.md             │
├─────────────────────────────────────────────────────┤
│ 3. SESSION END ("wrap up")                          │
│    Agent writes summary_<date>.md with files        │
│    changed, features done, issues, next steps       │
└─────────────────────────────────────────────────────┘

Example Log Entries

changes.md

### 2026-07-23 10:42 — EDIT — src/routes/orders.ts
Reason: Added validation for the quantity field per user request.
Before: `const qty = req.body.quantity;`
After:  `const qty = orderSchema.parse(req.body).quantity;`

commands.md

### 2026-07-23 10:45
Command: pnpm run typecheck
Status: FAILED — TS2345 in src/routes/orders.ts:18
Resolution: Fixed type mismatch; re-ran successfully at 10:47.

summary_2026-07-23.md

# Session Summary — 2026-07-23
## Files changed
- src/routes/orders.ts (validation added)
## Completed
- Order quantity validation with Zod
## Known issues
- Edge case: quantity of 0 returns generic error message
## Next steps
- Improve validation error messages
- Add unit tests for the orders route

Tips

  • Commit the history. Keep agentic_history/ in version control so it travels with the repo and survives environment resets.
  • Prune periodically. If logs grow large, archive old session files into agentic_history/archive/ — but always keep the latest summary.
  • Don't log secrets. Instruct the agent never to write API keys, tokens, or credentials into the history files.
  • Trim diffs for big changes. For large refactors, a snippet plus a reason is more useful than a 500-line diff.
  • One summary per session. The summary files are what future sessions rely on most — keep them sharp and actionable.

FAQ

Does this replace git history? No — git tells you what changed; agentic_history captures why, including the prompts and reasoning that led to the change.

Will this slow the agent down? Slightly, but the payoff is continuity. For fast-iteration sessions you can relax rule 4 to log summaries instead of full diffs.

Can multiple developers share it? Yes — that's a key benefit. Each session file records who ran it (add your name to the session header if working on a team).

Clone this wiki locally