entirecontext 0.1.1

Time-travel searchable agent memory anchored to your codebase

EntireContext

Git-anchored decision memory for coding agents.

⚠️ Experimental — API and data format may change without notice.

EntireContext captures AI coding work as it happens, distills decisions and lessons from it, and brings the right context back when similar code changes happen again.

Why It Exists

AI coding tools generate changes quickly, but engineering judgment still gets buried in chat logs. Important decisions, rejected alternatives, and hard-won lessons disappear across sessions, repos, and agents, so teams keep rediscovering the same context.

EntireContext turns session history into reusable engineering memory tied to commits, diffs, checkpoints, and files instead of leaving it as raw transcript storage.

Core Product Loop

• Capture — sessions, turns, tool calls, and checkpoints are recorded through hooks and anchored to git history
• Distill — assessments, feedback, and lessons convert raw session history into reusable judgment
• Retrieve — search, graph traversal, attribution, and rewind surface the most relevant prior context
• Intervene — agents and humans can apply past decisions before the next related change lands

What Makes EntireContext Different

• Git-anchored memory — context is tied to commits, branches, diffs, and checkpoints
• Decision-oriented, not chat-oriented — the goal is reusable engineering judgment, not transcript hoarding
• Built for coding agents — native hook integration plus MCP access for in-session retrieval
• Per-repo and cross-repo — preserve local project context while allowing broader learning patterns

Key Capabilities

• Decision capture and assessment — futures assessments, typed relationships, feedback loops, and lessons
• Git time-travel — checkpoints, rewind, blame, and historical inspection
• Context retrieval — regex, FTS5, semantic, and hybrid search across sessions and repos
• Agent-facing interfaces — MCP tools for search, checkpoints, assessments, graph traversal, and trends
• Operational support — sync, filtering, consolidation, dashboarding, export, and migration tools

Who It's For

• Engineers already using coding agents in day-to-day development
• Small teams that want decisions and lessons to accumulate instead of disappearing into chat history
• Repositories where historical intent matters as much as the final diff

AGENTS.md Templates

If you want agents to reuse stored decisions consistently, start from these templates:

• entirecontext maintainers: docs/templates/entirecontext-maintainer-decision-reuse-template.md
• Projects using EntireContext: docs/templates/entirecontext-user-decision-reuse-template.md

Adding Proactive EntireContext Guidance

If you also want agents to proactively check broader EntireContext memory, add a repository-specific section to your AGENTS.md.

Recommended placement:

• Near other agent workflow rules or memory lookup rules
• Immediately after any OneContext/Aline history-search block if you already have one
• Keep the <!-- ENTIRECONTEXT:START --> and <!-- ENTIRECONTEXT:END --> markers so the block is easy to find and update later

This complements the decision-reuse templates above. Use it when you want agents to check not only decisions, but also assessments, lessons, checkpoints, attribution, sessions, and turns before answering or implementing non-trivial work.

Example block to add:

<!-- ENTIRECONTEXT:START -->
## EntireContext - Proactive Memory Reuse

When the repository has EntireContext available, **proactively** use EntireContext
before answering questions about existing code, prior decisions, debugging context,
historical implementation details, repeated regressions, or earlier agent work.
Do not wait for the user to explicitly ask for a memory lookup.

Prefer EntireContext first for repository-scoped memory such as decisions,
assessments, lessons, checkpoints, attribution, sessions, and turns.
Use OneContext/Aline as a fallback when the user explicitly asks for Aline history
or when EntireContext does not contain the needed context.

Scenarios to proactively use EntireContext:
- User asks "why was X implemented this way?" or asks for prior rationale
- User is debugging behavior that may have previous fixes, regressions, or lessons
- User references a function, file, subsystem, checkpoint, session, or decision that may already exist in memory
- The task changes behavior, policy, schema, interface, lifecycle, sync, ranking, hooks, telemetry, or other long-lived system behavior
- You need prior assessments, lessons, attribution, or related turns before proposing non-trivial changes

Preferred retrieval order:
1. Decision-specific lookup (`ec_decision_related`, `ec_decision_list`, `ec_decision_get`)
2. Broader repo memory lookup (`ec_related`, `ec_search`, `ec_session_context`)
3. Deep inspection (`ec_turn_content`, `ec_checkpoint_list`, `ec_attribution`, `ec_lessons`, `ec_assess_trends`)

If no relevant EntireContext records exist, state that explicitly before proceeding
with new reasoning.

### Decision Capture — Recording What Was Decided

Retrieval alone loses decisions that were never recorded. Proactively **create**
decision records during the session, not only at the end.

When to record a decision (`ec_decision_create`):
- You compared alternatives and chose one (record what was rejected and why)
- You changed architecture, module boundaries, data flow, or public interfaces
- You established a convention, policy, or constraint that future work should follow
- A debugging session revealed a root cause that changes how the system should behave

When to record a decision outcome (`ec_decision_outcome`):
- Completed work confirmed, contradicted, refined, or replaced a prior decision
- A decision was applied and the result validated or invalidated its rationale

Capture timing:
- Record **during** the session as decisions happen — do not defer to SessionEnd
- SessionEnd auto-extraction (`maybe_extract_decisions`) is a fallback, not the primary path
- If you realize a past session made an unrecorded decision, record it retroactively
<!-- ENTIRECONTEXT:END -->

Quick Start

Choose an install path first:

• Local dependency (inside a Python/uv project)
• Global install (optional) for using ec as a standalone CLI across any repo

Use global install (optional) when you want ec like an app/tool. Use local dependency when you want to manage entirecontext in a Python project's dependencies.

# 1A. Local dependency (Python/uv project)
uv add entirecontext
# or: pip install entirecontext

# 1B. Global install (optional, recommended for non-Python repos)
uv tool install entirecontext
# alternative:
pipx install entirecontext

Use the same workflow after either install path:

# 2. Initialize in your repo
cd your-project
ec init

# 3. Install Claude Code hooks
ec enable

# 4. Use Claude Code as usual — sessions are captured automatically

# 5. Query your history
ec search "authentication"
ec search "refactor" --fts
ec session list
ec blame src/main.py
ec checkpoint list

Windows Notes

• Install alternative (Python launcher): py -m pip install entirecontext
• PowerShell example:

  ec init
  ec enable
  ec search "authentication"
  

• If ec is not recognized, open a new terminal (or sign out/in) so updated PATH is loaded.
• For uv tool/pipx installs, ensure the scripts directory is on PATH.

CLI Reference

The sections below are reference material for the current CLI surface. They stay close to the implemented interface on purpose so the product narrative above does not drift from what the tool actually does.

Top-Level Commands

Command	Description
ec init	Initialize EntireContext in current git repo
ec enable [--no-git-hooks]	Install Claude Code hooks and git hooks (skip git hooks with --no-git-hooks)
ec disable	Remove Claude Code hooks
ec status	Show capture status (project, sessions, turns, active session)
ec config [KEY] [VALUE]	Get or set configuration (dotted keys)
ec doctor	Diagnose issues (schema, hooks, unsynced checkpoints)
ec search QUERY	Search across sessions, turns, and events
ec blame FILE [-L START,END] [--summary]	Show per-line human/agent attribution
ec rewind CHECKPOINT_ID	Show or restore code state at a checkpoint
ec sync [--no-filter]	Export to shadow branch, then push with one automatic artifact-merge retry on non-fast-forward (skip secret filtering with --no-filter)
ec pull	Fetch latest origin shadow branch snapshot and import
ec index [--semantic] [--force] [--model NAME]	Rebuild FTS5 indexes, optionally generate embeddings
ec dashboard [--since DATE] [--limit N]	Show team dashboard: sessions, checkpoints, assessment trends
ec graph [--session ID] [--since DATE] [--limit N]	Show knowledge graph of git entities
ec ast-search QUERY [--type TYPE] [--file PATH] [--limit N]	Search indexed Python AST symbols

ec session Subcommands

Command	Description
ec session list	List sessions (with turn counts and status)
ec session show SESSION_ID	Show session details and turn summaries
ec session current	Show current active session
ec session export ID [--output FILE]	Export session as Markdown (YAML frontmatter + sections)
ec session graph [--agent ID] [--session ID] [--depth N]	Visualise multi-agent session graph
ec session activate [--turn ID] [--session ID] [--hops N] [--limit N]	Find related turns via spreading activation
ec session consolidate [--before DATE] [--session ID] [--limit N] [--execute]	Compress old turn content (dry-run by default)

ec checkpoint Subcommands

Command	Description
ec checkpoint list	List checkpoints (commit, branch, diff summary)
ec checkpoint show CHECKPOINT_ID	Show checkpoint details and file snapshot
ec checkpoint diff ID1 ID2	Diff between two checkpoints

ec event Subcommands

Command	Description
ec event list	List events (filter by --status, --type)
ec event show EVENT_ID	Show event details and linked sessions
ec event create TITLE	Create event (--type task|temporal|milestone)
ec event link EVENT_ID SESSION_ID	Link a session to an event

ec futures Subcommands

Command	Description
ec futures assess [-c CHECKPOINT] [-r ROADMAP] [-m MODEL] [-b BACKEND]	Assess staged diff or checkpoint against roadmap via LLM
ec futures list [-v VERDICT] [-n LIMIT]	List assessments (filter by --verdict)
ec futures feedback ID FEEDBACK [-r REASON]	Add agree/disagree feedback to an assessment
ec futures lessons [-o OUTPUT] [-s SINCE]	Generate LESSONS.md from assessed changes with feedback
ec futures trend [--since DATE] [--limit N]	Show cross-repo assessment trend analysis
ec futures relate SRC TYPE TGT [--note TEXT]	Add typed relationship between assessments
ec futures relationships ID [--direction DIR]	List relationships for an assessment
ec futures unrelate SRC TYPE TGT	Remove a typed relationship
ec futures tidy-pr [--since DATE] [--limit N] [--output FILE]	Generate tidy PR draft from narrow assessments
ec futures report [--since DATE] [--limit N] [--output FILE]	Generate team-shareable Markdown report
ec futures worker-status	Show background assessment worker status
ec futures worker-stop	Stop background assessment worker
ec futures worker-launch [--diff TEXT]	Launch background assessment worker
ec decision create TITLE [--rationale TEXT] [--scope TEXT]	Create a decision record
ec decision list [--status STATUS] [--file PATH] [--limit N]	List decisions (optional staleness/file filter)
ec decision show DECISION_ID	Show decision details and linked artifacts
ec decision link DECISION_ID [--assessment ID|--checkpoint ID|--commit SHA|--file PATH]	Link decision to assessment/checkpoint/commit/file
ec decision stale DECISION_ID --status STATUS	Update decision staleness (fresh|stale|superseded|contradicted)

LLM Backends (ec futures assess)

Backend	Flag	Auth	Default Model
openai	-b openai	OPENAI_API_KEY	gpt-4o-mini
github	-b github	GITHUB_TOKEN	openai/gpt-4o-mini
ollama	-b ollama	None (local)	llama3
codex	-b codex	CLI subprocess	—
claude	-b claude	CLI subprocess	—

ec purge Subcommands

Command	Description
ec purge session SESSION_ID [--execute] [--force]	Purge a session and all its turns (dry-run by default)
ec purge turn TURN_ID... [--execute]	Purge specific turns by ID
ec purge match PATTERN [--execute] [--force]	Purge turns matching a regex pattern

ec import Command

Command	Description
ec import --from-aline [PATH]	Import sessions/turns/checkpoints from Aline DB

Options: --workspace, --dry-run, --skip-content

ec repo Subcommands

Command	Description
ec repo list	List all registered EntireContext projects

Common Flags

Flag	Description
-g, --global	Search/list across all registered repos
-r, --repo NAME	Filter by repo name (repeatable)
-n, --limit N	Max results (default 20)

Search Options

Flag	Description
--fts	Use FTS5 full-text search
--semantic	Use semantic search (requires entirecontext[semantic])
--hybrid	Use hybrid search (FTS5 + recency RRF reranking)
--file PATH	Filter by file path
--commit HASH	Filter by commit hash
--agent TYPE	Filter by agent type
--since ISO8601	Filter by date
-t TARGET	Search target: turn (default), session, event, content

MCP Server

EntireContext exposes the same retrieval and assessment primitives to coding agents over MCP so the memory loop can run inside active coding sessions, not only through the CLI.

Automatic Setup

ec enable automatically registers the MCP server in ~/.claude/settings.json (user-level):

ec enable    # installs hooks AND configures MCP server
ec doctor    # verify MCP config is present

This is idempotent — running ec enable again skips the MCP entry if it already exists. ec disable removes hooks but preserves the MCP config (other repos may use it).

Manual Setup

To configure manually, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "entirecontext": {
      "command": "ec",
      "args": ["mcp", "serve"],
      "type": "stdio"
    }
  }
}

Manual Removal

To remove the MCP server, delete the entirecontext key from ~/.claude/settings.json:

# Remove MCP config (use jq or edit manually)
jq 'del(.mcpServers.entirecontext)' ~/.claude/settings.json > tmp.json && mv tmp.json ~/.claude/settings.json

Standalone Server

To run the MCP server directly (e.g. for debugging):

ec mcp serve

Available Tools

Tool	Description
ec_search	Search turns/sessions with regex or FTS5. Filters: file_filter, commit_filter, agent_filter, since
ec_checkpoint_list	List checkpoints, optionally filtered by session_id and since
ec_session_context	Get session details with recent turns. Auto-detects current session if session_id omitted
ec_attribution	Get human/agent attribution for a file, with optional line range
ec_rewind	Show state at a specific checkpoint
ec_related	Find related sessions/turns by query text or file paths
ec_turn_content	Get full content for a specific turn (including JSONL content files)
ec_assess	Assess staged diff or checkpoint against roadmap via LLM
ec_assess_create	Create an assessment programmatically (verdict, impact, suggestion)
ec_feedback	Add agree/disagree feedback to an assessment
ec_lessons	Generate LESSONS.md from assessed changes with feedback
ec_assess_trends	Cross-repo assessment trend analysis (verdict distribution, feedback stats)

All tools accept a repos parameter for cross-repo queries: null = current repo, ["*"] = all repos, ["name"] = specific repos.

Hook System

ec enable installs two kinds of hooks automatically. No manual intervention required.

Claude Code Hooks (.claude/settings.local.json)

Hook Type	Trigger	Action
SessionStart	Claude Code session begins	Create/resume session record
UserPromptSubmit	User sends a message	Record turn start
Stop	Assistant completes response	Record turn end with summary
PostToolUse	Tool call completes	Track files touched and tools used
SessionEnd	Claude Code session ends	Finalize session, generate summary

Hook protocol: stdin JSON, exit code 0 = success, 2 = block.

Git Hooks (.git/hooks/)

Hook	Trigger	Action
post-commit	git commit	Create checkpoint tied to the new commit if a session is active
pre-push	git push	Run ec sync if auto_sync_on_push is enabled

Skip git hook installation with ec enable --no-git-hooks. Both hooks are removed by ec disable.

Configuration

Config merges in order: defaults ← global (~/.entirecontext/config.toml) ← per-repo (.entirecontext/config.toml).

Default Configuration

[capture]
auto_capture = true
checkpoint_on_commit = true

[capture.exclusions]
enabled = false
content_patterns = []    # regex — skip turns matching these
file_patterns = []       # glob — exclude files from tracking
tool_names = []          # exact — skip tool usage recording
redact_patterns = []     # regex — replace matches with [FILTERED] before storage

[search]
default_mode = "regex"
semantic_model = "all-MiniLM-L6-v2"

[sync]
auto_sync = false
auto_pull = false
cooldown_seconds = 300
pull_staleness_seconds = 600
push_on_sync = true
quiet = true

[display]
max_results = 20
color = true

[security]
filter_secrets = true
patterns = [
    '(?i)(api[_-]?key|secret|password|token)\s*[=:]\s*[\'"]?[\w-]+',
    '(?i)bearer\s+[\w.-]+',
    'ghp_[a-zA-Z0-9]{36}',
    'sk-[a-zA-Z0-9]{48}',
]

[filtering.query_redaction]
enabled = false
patterns = []            # regex — redact matches in search/MCP results
replacement = "[FILTERED]"

CLI Usage

ec config                              # show all config
ec config search.default_mode          # get a value
ec config search.default_mode fts      # set a value
ec config security.filter_secrets true # set a value

Sync Policy

Shadow branch sync uses artifact-level merge only on entirecontext/checkpoints/v1.

• ec sync performs one automatic retry only, and only when the first push is rejected as non-fast-forward.
• The retry path fetches origin/entirecontext/checkpoints/v1, merges exported artifacts, creates a new commit, and pushes again.
• ec pull imports from the latest origin/<shadow-branch> remote-tracking snapshot, not from the local shadow branch.
• There is no git conflict UI and no general git 3-way merge support in this path.
• Artifact merge policy:
  • manifest.json: key union; higher total_turns wins for duplicate session entries.
  • sessions/<id>/meta.json: higher total_turns wins; ties preserve non-null fields; started_at uses earlier value; ended_at uses later value.
  • sessions/<id>/transcript.jsonl: deduplicate by turn id.
  • checkpoints/*.json: filename union.
• Malformed remote artifacts, missing remote shadow snapshots, and retry push failures are explicit sync errors.

Architecture

Sessions, turns, and checkpoints flow from Claude Code hooks through the core business logic into SQLite, with optional export via shadow branch sync.

CLI (Typer)  →  core/  →  db/  →  hooks/  →  sync/
cli/             business    SQLite     Claude Code   shadow branch
  project_cmds   logic       schema     integration   export/import
  session_cmds   config      migration  turn capture  merge
  search_cmds    security    connection session lifecycle
  hook_cmds      cross_repo
  checkpoint_cmds attribution
  sync_cmds      event
  rewind_cmds    indexing
  repo_cmds      search
  event_cmds     futures
  blame_cmds     llm
  index_cmds     import_aline
  mcp_cmds       content_filter
  futures_cmds   purge
  import_cmds    export
  purge_cmds     report
  graph_cmds     tidy_pr
  ast_cmds       dashboard
  dashboard_cmds ast_index
               knowledge_graph
               agent_graph
               activation
               consolidation
               hybrid_search
               async_worker

mcp/server.py — MCP server interface (optional dependency)

Data Model

Table	Purpose
projects	Registered repos (name, path, remote URL)
sessions	Captured sessions (type, title, summary, turn count)
turns	Individual turns (user message, assistant summary, files touched)
turn_content	JSONL content file references for full turn data
checkpoints	Git-anchored snapshots (commit hash, branch, file snapshot, diff)
agents	Agent identities (type, role, parent agent)
events	Grouping mechanism (task / temporal / milestone)
event_sessions	Many-to-many link between events and sessions
event_checkpoints	Many-to-many link between events and checkpoints
assessments	Futures assessment results (verdict, impact, feedback)
assessment_relationships	Typed links between assessments (causes/fixes/contradicts)
attributions	Per-line human/agent file attribution
embeddings	Semantic search vectors
ast_symbols	Python AST symbol index (functions, classes, methods)
sync_metadata	Shadow branch sync state

FTS5 virtual tables: fts_turns, fts_events, fts_sessions, fts_ast_symbols — auto-synced via triggers.

Data Locations

Path	Contents
.entirecontext/db/local.db	Per-repo SQLite database
.entirecontext/content/	JSONL turn content files
.entirecontext/config.toml	Per-repo configuration
~/.entirecontext/db/ec.db	Global database (cross-repo registry)
~/.entirecontext/config.toml	Global configuration

Development

git clone https://github.com/teslamint/entirecontext.git
cd entirecontext
uv sync --extra dev

Run Tests

uv run pytest                          # all tests
uv run pytest tests/test_core.py       # single file
uv run pytest -k "test_search"         # by name pattern
uv run pytest --cov=entirecontext      # with coverage

Lint & Format

uv run ruff format .                   # format (line-length 120)
uv run ruff check . --fix              # lint + autofix

Optional Extras

Extra	Dependencies	Purpose
dev	pytest, pytest-cov, ruff	Testing and linting
semantic	sentence-transformers	Semantic search with embeddings
mcp	mcp	MCP server for AI agent integration

Install extras: uv sync --extra dev --extra semantic --extra mcp

Development Context

This project's entire AI development history is available on the entirecontext/checkpoints/v1 branch.

Acknowledgments

EntireContext was inspired by:

• entireio/cli — Git-integrated AI agent session capture and context management
• TheAgentContextLab/OneContext — Agent self-managed context layer for unified AI agent memory
• The Futures Assessment feature (ec futures) is inspired by Kent Beck's Earn And Learn and the Tidy First philosophy — analyzing whether each change expands or narrows your project's future options.

License

MIT

Decision / Assessment / Lesson roles

• Decision: reusable engineering intent (what/why/scope), linked to files, checkpoints, and assessments.
• Assessment: point-in-time evaluation of a diff/checkpoint (expand/narrow/neutral) using Tidy First framing.
• Lesson: assessment + feedback distilled into guidance for future changes.

MCP Decision Tools

• ec_decision_get(decision_id) — resolve decision by full or prefix ID.
• ec_decision_related(files?, assessment_ids?, diff_text?, limit?) — rank linked decisions by file overlap, assessment relations, and diff text match.