Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/affaan-m/ECC/llms.txt

Use this file to discover all available pages before exploring further.

Context rot — the gradual degradation of an agent’s working memory as a session grows — is one of the most common sources of wasted tokens and failed tasks. ECC addresses this at the infrastructure level: a SQLite state store records each session’s lifecycle, skill runs, architectural decisions, and linked work items. When you start a new session, the context from your last session is available immediately rather than reconstructed from memory.

​
Session Lifecycle

Every ECC-managed session moves through a defined lifecycle driven by hooks:
  1. SessionStart — The session-start.js hook fires when Claude Code opens a new session. It loads context from the previous session snapshot, injects learned instincts (up to ECC_MAX_INJECTED_INSTINCTS, default 6), and primes the agent with project context. Context loading is bounded: ECC_SESSION_START_MAX_CHARS caps the injected text at 8,000 characters by default.
  2. Work phase — The agent works, producing tool calls, file edits, and decisions recorded in the session transcript.
  3. PreCompact — Before Claude Code compacts the context window, the pre-compact.js hook saves important state to a file so the compacted session retains situational awareness.
  4. Stop — When the session ends, the session-end.js hook persists a session summary to ~/.claude/session-data/. The evaluate-session.js hook extracts patterns from the session and feeds them to the continuous learning system. 
SessionStart  →  Work  →  PreCompact (optional)  →  Stop
     ↓                          ↓                      ↓
 Load context            Save mid-session          Persist
 Inject instincts         state snapshot           summary +
 Prime agent                                       extract patterns

​
CLI Commands for Session Management

All session management commands are available through the npx ecc CLI: 
# List recent sessions from the SQLite state store (default: 10)
npx ecc sessions

# List with JSON output
npx ecc sessions --json

# List more sessions
npx ecc sessions --limit 20

# Inspect a specific session by ID
npx ecc sessions <session-id>

​
Session Resume Pattern

ECC provides /save-session and /resume-session commands for explicit, human-readable session handoffs. These work independently of the automatic hook-based persistence — they are for intentional, structured context capture.

​
Saving a Session

Run /save-session at the end of a work session or before hitting context limits. The command gathers context from the conversation, reads all modified files, and writes a structured snapshot to ~/.claude/session-data/YYYY-MM-DD-<short-id>-session.tmp: 
/save-session
The session file is a markdown document containing:
  • What We Are Building — project context and goal
  • What WORKED (with evidence) — confirmed working items
  • What Did NOT Work (and why) — failed approaches with exact reasons
  • What Has NOT Been Tried Yet — queued approaches
  • Current State of Files — per-file status table
  • Decisions Made — architectural choices and rationale
  • Blockers & Open Questions — unresolved items
  • Exact Next Step — precise starting point for the next session

​
Resuming a Session

Start any new session with /resume-session to load the previous session’s context before doing any work: 
# Load the most recent session file
/resume-session

# Load by date
/resume-session 2024-01-15

# Load a specific file
/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp
The command reads the session file completely, then responds with a structured briefing — project summary, current state, failed approaches to avoid, open questions, and the exact next step — before waiting for you to direct it.
The “What Did NOT Work” section is the most valuable part of a session file. Future sessions will blindly retry failed approaches without it. Write the exact reason each approach failed, not just that it failed.

​
Bounded Context Loading

Session context injection at SessionStart is bounded by two environment variables to prevent stale sessions from consuming the entire context window: 
# Cap SessionStart context injection at 4000 characters (default: 8000)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart context injection entirely (for local models or low-context setups)
export ECC_SESSION_START_CONTEXT=off

# Cap learned instinct injection (default: 6)
export ECC_MAX_INJECTED_INSTINCTS=6

# Minimum confidence required for an instinct to be injected, 0–1 (default: 0.7)
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7
Session files are pruned automatically after ECC_SESSION_RETENTION_DAYS (default: 30). Set to 0, off, false, disabled, never, or none to keep all session files: 
export ECC_SESSION_RETENTION_DAYS=14

​
Install-State Tracking

ECC records what was installed, when, and how in its SQLite state store. This powers npx ecc doctor (which detects drift) and npx ecc repair (which restores missing files without a full reinstall): 
# What does ECC think is installed?
npx ecc list-installed

# Are any ECC-managed files missing or drifted?
npx ecc doctor
npx ecc doctor --target cursor

# Restore drifted files (preview first)
npx ecc repair --dry-run
npx ecc repair
Each installation record captures:
  • Modules installed and their resolved paths
  • Target harness and profile used
  • Operations applied (copy, write, merge)
  • Timestamp of install
If your local Claude setup was wiped or reset, run npx ecc list-installed, then npx ecc doctor and npx ecc repair before reinstalling anything. This usually restores ECC-managed files without rebuilding your entire setup.

​
Decision Log

ECC session snapshots include an explicit decisions section. When the agent makes an architectural choice — selecting a library, accepting a tradeoff, choosing one approach over another — that decision and its rationale should be recorded before moving on. This prevents the next session from relitigating settled choices. Session file format for decisions: 
## Decisions Made

- **httpOnly cookie over localStorage** — reason: prevents XSS token theft, works with SSR
- **Custom auth over Next-Auth** — reason: Next-Auth conflicts with our Prisma setup
- **Sonnet for implementation, Opus for security review** — reason: cost/quality tradeoff

​
Example: npx ecc sessions Output

Recent sessions:

- sess_01j9abc123 [claude/session-start] active
  Repo: /Users/you/projects/my-app
  Started: 2024-01-15T14:32:00Z
  Ended: (active)
  Workers: 0

- sess_01j9abc456 [claude/session-start] completed
  Repo: /Users/you/projects/my-app
  Started: 2024-01-14T09:15:00Z
  Ended: 2024-01-14T17:42:00Z
  Workers: 2

- sess_01j9abc789 [cursor/session-start] completed
  Repo: /Users/you/projects/api-service
  Started: 2024-01-13T11:00:00Z
  Ended: 2024-01-13T15:30:00Z
  Workers: 0

Total sessions: 3
To inspect a session in detail — including workers, skill runs, and decisions: 
npx ecc sessions sess_01j9abc456
npx ecc sessions sess_01j9abc456 --json

​
Continuous Learning Integration

The session stop hook runs evaluate-session.js, which extracts reusable patterns from the session transcript and feeds them to the continuous learning v2 system. Extracted patterns become instincts — high-confidence, reusable knowledge pieces that are injected at the start of future sessions. Manage instincts directly: 
# View learned instincts with confidence scores
/instinct-status

# Import instincts from a file or teammate
/instinct-import <file>

# Export your instincts for sharing
/instinct-export

# Cluster related instincts into durable skills
/evolve

# Delete expired pending instincts (30-day TTL)
/prune

Build docs developers (and LLMs) love

Get started for freeTalk to us