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.

ECC’s memory-persistence hooks form a lifecycle contract that keeps agent context coherent across session restarts and context compactions. Rather than starting each session cold, the session:start hook loads a bounded snapshot of prior state — active work items, recent decisions, session metadata — while pre:compact saves a fresh snapshot before the harness truncates history. This design prevents context loss without flooding the context window.

​
Lifecycle Contract

The full memory-persistence hook table, sourced from hooks/memory-persistence/:
EventHook IDPurposeBlocking
SessionStartsession:startLoad bounded prior context and project metadataNo
PreCompactpre:compactSave state before compactionNo
PreToolUsepre:observe:continuous-learningCapture tool intent for learning signalsNo
PostToolUsepost:observe:continuous-learningCapture tool result for learning signalsNo
PostToolUsepost:session-activity-trackerRecord tool and file activity for ECC2 metricsNo
Stopstop:format-typecheckBatch quality gate after editsYes (on hook failure)
Stopstop:check-console-logAudit modified files for debug loggingWarn/error by hook output

​
Session Execution Flow

Session begins
      ↓
SessionStart → session:start
  • Load prior context snapshot (bounded to ECC_SESSION_START_MAX_CHARS)
  • Detect project state and package manager
  • Prepare session metadata

...agent work...

Each tool call:
  PreToolUse → pre:observe:continuous-learning (capture intent)
  PostToolUse → post:observe:continuous-learning (capture result)
             → post:session-activity-tracker (metrics)

Context nearing limit:
  PreCompact → pre:compact
  • Save current session snapshot to SQLite
  • Export active skill runs and pending decisions

Agent responds:
  Stop → stop:format-typecheck (quality gate)
       → stop:check-console-log (debug log audit)

Session ends → SessionEnd
  • Final state persist
  • Cleanup log

​
Bounded Context Loading

The session:start hook loads only a relevant snapshot — not the full history. This is the key design choice that prevents context window exhaustion in long-running or frequently-restarted sessions.
Set ECC_SESSION_START_MAX_CHARS to tune how much prior context is loaded. Smaller values preserve more of the context window for active work; larger values give the agent richer history to draw on.
# Default: 8000 characters
export ECC_SESSION_START_MAX_CHARS=8000

# Tighter for small context windows
export ECC_SESSION_START_MAX_CHARS=3000

# Disable session context loading entirely
export ECC_SESSION_START_CONTEXT=off

​
What Gets Persisted

The pre:compact and session-end hooks save:
  • Session ID, harness, repo root, start time
  • Active skill runs (in-progress, with tokens used)
  • Pending decisions (title, rationale, alternatives)
  • Current work items (linked Linear, GitHub, handoff items)
  • Recent tool-use observations (for continuous learning)
The post:observe:continuous-learning hook captures:
  • Tool name and input (truncated for token safety)
  • Tool output summary
  • Timestamp and session ID
These observations feed the continuous-learning skill, which extracts patterns at the end of a session for future skill evolution.
The post:session-activity-tracker hook records for ECC2 metrics:
  • Tool name and invocation count
  • File paths touched
  • Session ID reference
  • Timestamp
These metrics are visible in npx ecc status and the ECC2 control pane.

​
Script Implementations

The hooks delegate to scripts in scripts/hooks/:
ScriptRole
session-start.jsLoads bounded prior context, detects project state
pre-compact.jsCaptures state snapshot before context compaction
session-end.jsPersists session-end summaries from transcript metadata
observe-runner.jsRecords tool-use observations for continuous learning
session-activity-tracker.jsRecords tool usage and file activity for ECC2

​
Installation

Memory-persistence hooks are part of the hooks-runtime module, included in the core profile and above: 
# Install with core profile (recommended)
npx ecc install --profile core --target claude

# Or install just the hooks module
npx ecc install --modules hooks-runtime --target claude

​
Operator Privacy Defaults

ECC’s memory-persistence design follows these defaults:
  • Local only — all persistence goes to the local SQLite state store, never to hosted services unless you explicitly enable an integration
  • Transcript-safe — no raw transcripts are exported; only structured summaries and observations
  • Opt-out available — disable via ECC_SESSION_START_CONTEXT=off or ECC_DISABLED_HOOKS
  • Profile-gated — all hooks respect ECC_HOOK_PROFILE (minimal/standard/strict)
# Disable all memory persistence hooks
export ECC_DISABLED_HOOKS="session:start,pre:compact,post:observe:continuous-learning,post:session-activity-tracker"

# Or use minimal profile (essential lifecycle only)
export ECC_HOOK_PROFILE=minimal

Build docs developers (and LLMs) love

Get started for freeTalk to us