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