Git Context Controller (GCC)

Overview

GCC transforms agent memory from a passive token stream into a structured, versioned file system under .GCC/. Inspired by Git, it provides four operations — COMMIT, BRANCH, MERGE, CONTEXT — to persist milestones, explore alternatives in isolation, synthesize results, and recover historical context efficiently.

Initialization

On first use, check if .GCC/ exists in the project root. If not, run scripts/gcc_init.sh to create the directory structure:

.GCC/
├── main.md          # Global roadmap and objectives
├── metadata.yaml    # Infrastructure state (branches, file tree, config)
├── commit.md        # Commit history for main branch
├── log.md           # OTA execution log for main branch
└── branches/        # Isolated workspaces for experiments
    └── <branch-name>/
        ├── commit.md
        ├── log.md
        └── summary.md

For detailed file format specifications, read references/file_formats.md.

Configuration

GCC behavior is controlled via metadata.yaml:

• proactive_commits: true — Automatically suggest commits after completing coherent sub-tasks
• proactive_commits: false — Only commit when explicitly requested

Toggle with: "enable/disable proactive commits" or by editing metadata.yaml.

Commands

COMMIT

Persist a milestone on the current branch.

Triggers: /gcc commit <summary>, "commit this progress", "save this milestone", "checkpoint" Procedure:

• Read the current branch's commit.md to determine the next commit number
• Append a new entry to commit.md with:

- Sequential ID (e.g., [C004])

- Date (UTC ISO 8601)

- Current branch name

- Branch purpose (from summary.md if on a branch, or from main.md)

- Previous progress summary (1-2 sentences from last commit)

- This commit's contribution (detailed technical description with files touched)

• Append an OTA entry to log.md recording the commit action
• Update metadata.yaml file tree if files were created/modified
• If on main branch, update milestones section in main.md

Proactive behavior: When proactive_commits: true, suggest a commit after:

• Completing a function, module, or coherent unit of work
• Fixing a bug and verifying the fix
• Finishing a research/exploration phase with conclusions
• Any point where losing context would mean re-doing significant work

BRANCH

Create an isolated workspace for exploring an alternative approach.

Triggers: /gcc branch <name>, "branch to try...", "explore alternative...", "experiment with..." Procedure:

• Create .GCC/branches/<branch-name>/ directory
• Create summary.md with: purpose, parent branch, creation date, key hypotheses
• Create empty commit.md and log.md for the branch
• Update metadata.yaml to register the new branch
• Update main.md Active Branches section
• Log the branch creation in the parent branch's log.md

From this point, all COMMITs and OTA logs go to the branch-specific files until a MERGE or explicit branch switch.

MERGE

Integrate a completed branch back into the main flow.

Triggers: /gcc merge <branch>, "merge results from...", "integrate the experiment", "branch X is done" Procedure:

• Read the branch's summary.md and commit.md to understand outcomes
• Append a synthesis commit to main's commit.md summarizing:

- What was tried

- What was learned

- What is being integrated (or why the branch is being abandoned)

• Update main.md:

- Add milestone entry with branch results

- Remove from Active Branches

- Update objectives if applicable

• Update metadata.yaml: set branch status to merged or abandoned
• Log the merge in main's log.md

CONTEXT

Retrieve historical memory at different resolution levels.

Triggers: /gcc context <flag>, "what did we do on...", "recover context", "show me the history", "where were we" Flags:

• --branch [name] — Read summary.md and latest commits for a specific branch (or current branch if no name). Provides high-level understanding of what happened and why.

• --log [n] — Read last N entries (default 20) from the current branch's log.md. Provides fine-grained OTA traces for debugging or resuming interrupted work.

• --metadata — Read metadata.yaml to recover project structure: file tree, dependencies, active branches, configuration.

• --full — Read main.md for the complete project roadmap, all milestones, and active branches. Use for cross-session recovery or handoff to another agent.

When no flag is specified, default to --branch for the current active branch.

OTA Logging

Throughout all work (not just during explicit commands), maintain the OTA execution log:

• Observation: What was noticed or discovered
• Thought: Reasoning about what to do next
• Action: What action was taken

Append entries to the active branch's log.md. Keep a maximum of 50 entries; when exceeding, remove the oldest entries. Each entry includes a sequential ID, timestamp, and branch name.

Log OTA entries at meaningful decision points — not every single action, but significant observations, strategy changes, and outcomes.

Cross-Session Recovery

When starting a new session on an existing project with .GCC/:

• Read metadata.yaml to understand project state and active branches
• Read main.md for the global roadmap and objectives
• Read the active branch's latest commits and log entries
• Resume work with full context of what was accomplished and what remains

Natural Language Mapping

User says	Command
"save/checkpoint/persist this"	COMMIT
"try a different approach"	BRANCH
"that experiment worked, integrate it"	MERGE
"where were we?" / "what's the status?"	CONTEXT --full
"what happened on branch X?"	CONTEXT --branch X
"show recent activity"	CONTEXT --log
"what files do we have?"	CONTEXT --metadata
"enable/disable auto-commits"	Toggle proactive_commits in metadata.yaml