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 windows close. Terminals restart. Without deliberate persistence, every new session begins from scratch — rediscovering the same patterns, revisiting the same decisions, re-navigating the same codebase. ECC solves this with a layered memory system: a SQLite-backed state store that persists structured facts about your sessions, and a set of lifecycle hooks that load, checkpoint, and save context at the right moments so the agent always begins with bounded, relevant history.

​
The ECC State Store

ECC’s canonical persistence layer is a SQLite state store whose schema is defined in schemas/state-store.schema.json. It tracks seven tables of structured state across all harness restarts:

sessions

One record per agent session — harness identity, repo root, state, start/end timestamps, and a JSON snapshot of session output.

skillRuns

Records every skill execution — which skill, which version, which session, outcome, tokens used, duration, and optional user feedback.

skillVersions

Tracks each version of a skill — content hash, amendment reason, promoted-at and rolled-back-at timestamps.

decisions

Records architectural and implementation decisions — title, rationale, alternatives considered, supersession links, and current status.

installState

Tracks what ECC modules are installed per target — target ID and root, profile, module list, install operations log, install timestamp, and source version.

governanceEvents

Captures governance-relevant events (secrets detected, policy violations, approval requests) with resolution tracking.

workItems

Work items synced from external trackers (Jira, GitHub Issues, etc.) — source, title, status, priority, URL, owner, and repo context.

​
Schema Overview

{
  "sessions": [
    {
      "id": "sess_abc123",
      "adapterId": "claude-code",
      "harness": "claude",
      "state": "completed",
      "repoRoot": "/home/user/projects/my-app",
      "startedAt": "2025-07-10T14:32:00Z",
      "endedAt": "2025-07-10T17:15:00Z",
      "snapshot": { "summary": "Implemented OAuth2 login flow..." }
    }
  ],
  "skillRuns": [
    {
      "id": "run_def456",
      "skillId": "tdd-workflow",
      "skillVersion": "1.2.0",
      "sessionId": "sess_abc123",
      "taskDescription": "Add tests for AuthService",
      "outcome": "success",
      "failureReason": null,
      "tokensUsed": 14200,
      "durationMs": 43000,
      "userFeedback": null,
      "createdAt": "2025-07-10T15:05:00Z"
    }
  ],
  "decisions": [
    {
      "id": "dec_ghi789",
      "sessionId": "sess_abc123",
      "title": "Use JWT over session cookies for auth tokens",
      "rationale": "Stateless auth required for horizontal scaling",
      "alternatives": ["session cookies", "opaque tokens"],
      "supersedes": null,
      "status": "active",
      "createdAt": "2025-07-10T14:55:00Z"
    }
  ],
  "workItems": [
    {
      "id": "wi_jkl012",
      "source": "jira",
      "sourceId": "APP-1042",
      "title": "Implement password reset flow",
      "status": "in-progress",
      "priority": "high",
      "url": "https://your-org.atlassian.net/browse/APP-1042",
      "owner": "affaan",
      "repoRoot": "/home/user/projects/my-app",
      "sessionId": "sess_abc123",
      "metadata": {},
      "createdAt": "2025-07-09T10:00:00Z",
      "updatedAt": "2025-07-10T14:32:00Z"
    }
  ]
}

​
Memory Persistence Hooks

The state store is populated and consumed by three lifecycle hooks that form ECC’s memory persistence contract:
1

SessionStart — load bounded prior context

When a new session opens, session-start.js queries the state store for the most recent session snapshot, relevant decisions, and active work items. It injects a bounded summary into the session context — giving the agent working memory without flooding the context window.
# Cap how much prior context is loaded (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable prior context loading entirely
export ECC_SESSION_START_CONTEXT=off
The hook also detects the project’s package manager and active repo root, so the agent starts oriented to the current project.
2

PreCompact — save state before compaction

Before the harness compacts the context window, pre-compact.js captures the current session state — progress, open decisions, active work items — and writes it to the state store. This means compaction never loses meaningful work context.The longform guide describes the philosophy: “A skill or command that summarizes and checks in on progress then saves to a file… The next day it can use that as context and pick up where you left off.”
3

Stop — persist session learnings

After each complete Claude response, session-activity-tracker.js records tool usage and file activity. The stop:check-console-log hook audits modified files. If a transcript path is available, session-summary.js persists the session state.The pattern extraction hook (stop:pattern-extraction) evaluates the session for extractable knowledge and queues it for the continuous-learning workflow.
The design decision to use a Stop hook (rather than UserPromptSubmit) for learning extraction is intentional. UserPromptSubmit runs on every single message — adding latency to every prompt. Stop runs once per response — lightweight and non-blocking during active sessions.

​
Bounded Context Loading

ECC deliberately limits how much prior context is loaded at session start. Unbounded context injection defeats the purpose — a 200k-token context window filled with old session logs has less effective capacity than one that loads 8,000 characters of well-structured prior state. The session start hook loads:
  • The most recent session snapshot (what was accomplished, what was tried, what remains)
  • Active decisions (architectural choices that are still in effect)
  • In-progress work items (current task context)
It does not load full transcript history, old tool outputs, or prior skill runs — those are queryable on demand, not injected wholesale. Session save files (written to ~/.claude/session-data/) contain three sections:
  • What worked — approaches verified with evidence
  • What failed — approaches attempted but abandoned, with reasons
  • What remains — outstanding work and next steps

​
CLI Inspection Commands

# Browse, search, and manage session history
/sessions

# Inspect current status — active sessions, work items, instinct scores
npx ecc status

# List and filter work items synced from external trackers
npx ecc work-items

# Save the current session before ending
/save-session

# Resume from the most recent saved session
/resume-session

​
Example: Session Inspection

Running /sessions produces output like: 
ECC Session Store — 12 sessions tracked

SESSION        STARTED              ENDED                HARNESS   STATE       REPO
sess_abc123    2025-07-10 14:32     2025-07-10 17:15     claude    completed   my-app
sess_def456    2025-07-09 09:15     2025-07-09 14:40     claude    completed   my-app
sess_ghi789    2025-07-08 16:00     —                    claude    interrupted  api-service

Most recent snapshot (sess_abc123):
  Implemented OAuth2 login flow with JWT tokens.
  Decisions: JWT over session cookies (active).
  Remaining: password reset flow, email verification.
  Worked: tdd-workflow (14.2k tokens, 43s), security-review.
  Failed: attempted cookie-based session — abandoned, incompatible with load balancer.

Work items in scope:
  APP-1042  [high]  Implement password reset flow  (in-progress)
  APP-1051  [med]   Add email verification         (open)

​
Operator Privacy Defaults

The state store is local by default. ECC’s memory persistence contract explicitly:
  • Keeps all persistence local — no transcript data is sent to hosted services unless you explicitly enable an integration
  • Bounds context loaded at session start via ECC_SESSION_START_MAX_CHARS
  • Allows full opt-out via ECC_SESSION_START_CONTEXT=off
  • Gates all lifecycle hooks through ECC_HOOK_PROFILE and ECC_DISABLED_HOOKS
For advanced memory patterns — dynamic system prompt injection, strategic context compaction, and the continuous learning workflow — see the Session Management guide and the skills/continuous-learning/ skill in the ECC repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us