GCC — Agent-Driven Memory

You have a Git-inspired Contextual Commit (GCC) memory system. Use it proactively during work — commit milestones, branch before experiments, orient with context. You are responsible for the quality of what gets recorded. Auto-commit is a fallback; your narrative commits and curated summaries are what make this memory useful to future sessions.

CLI Setup

bash

ONECONTEXT_REPO=$(python3 -c "import json; print(json.load(open('$HOME/.onecontext/config.json'))['repo_path'])")
alias onecontext="$ONECONTEXT_REPO/.venv/bin/onecontext"

Run this once per session. All commands below assume the alias is set.

Commands

COMMIT — after completing a coherent milestone

bash

onecontext commit --title "Implement JWT auth" \
  --notes "Replaced session cookies with JWT tokens. Simplifies API gateway and enables stateless scaling. Validated with integration tests."

Add --git to also create a Git commit, checkpointing both code and memory state:

bash

onecontext commit --title "Implement JWT auth" --notes "..." --git

Notes must explain what changed and why — not list files or echo commands. Write as if briefing an engineer joining tomorrow. Commit after features, fixes, refactors, successful tests, or before task switches.

Bad: --notes "edited io.py, ran tests" (too terse, no reasoning) Good: --notes "Defines a reusable file output abstraction write_file(path, content) in io.py. Validated with a test to ensure correctness and future extensibility."

BRANCH — before exploring an uncertain alternative

bash

onecontext branch create try-async-api --summary "Testing async endpoints for performance" --activate

MERGE — when a branch experiment succeeds

bash

onecontext merge try-async-api --target main

Add --git to also create a Git commit for the merge:

bash

onecontext merge try-async-api --target main --git

The merge command automatically retrieves the target branch's context first (showing its progress and history), then integrates the source branch's events and creates a merge commit entry.

After merge: curate main.md — update Active Decisions with what was decided, remove resolved Pending Questions.

CONTEXT — to orient yourself

bash

onecontext context                          # project overview + branches
onecontext context --branch main            # branch purpose + commits
onecontext context --commit 0               # latest commit detail
onecontext context --log --limit 20         # execution trace
onecontext context --metadata file_structure # project files

Use at session start, before merges, or when disoriented.

UPDATE-MAIN — curate the project roadmap

bash

onecontext update-main --section "Purpose" \
  --content "Full-stack Next.js SaaS portal. Core features: analytics dashboard, data sync, user engagement reporting."

bash

onecontext update-main --section "Active Decisions" \
  --content "- JWT for auth (decided in try-jwt branch)
- PostgreSQL for persistence
- Tailwind CSS for styling"

Sections: Purpose, Milestones, To-Do, Active Decisions, Pending Questions. These are the most-read parts of memory — keep them current, specific, and useful.

Curation — Your Core Responsibility

The value of GCC depends on you writing meaningful content, not on automation. Specifically:

At session start: Run onecontext context. If main.md sections contain placeholders like "(none yet)" or "(pending curation)", curate them based on what you learn during the session.

After backfill: The backfill script imports raw history but cannot summarize it intelligently. After a backfill completes:

•Run onecontext context --log --limit 50 to understand what happened
•Run onecontext update-main --section "Purpose" --content "..." with a real project description
•Update Active Decisions and Pending Questions based on patterns you see in the history

After major milestones: Commit first, then review whether main.md sections need updating. Update Milestones with what was achieved. Move completed To-Do items. Active Decisions should reflect current architectural choices. Pending Questions should list real open issues.

After merges: Update Active Decisions with what was decided. Remove resolved Pending Questions. Check off completed To-Do items and add any new ones.

Workflow

•Start session → onecontext context to orient
•Before experiment → onecontext branch create ...
•After milestone → onecontext commit --title ... --notes ...
•Experiment worked → onecontext merge ...
•Curate → onecontext update-main ... when sections are stale

Auto-commit fires every 5 min as fallback, but your narrative commits are far more valuable.

BACKFILL — import past history

bash

$ONECONTEXT_REPO/scripts/run_backfill.sh /path/to/workspace --dry-run   # preview
$ONECONTEXT_REPO/scripts/run_backfill.sh /path/to/workspace --branch main  # import

Imports ~/.claude/history.jsonl and ~/.codex/history.jsonl. Creates daily commits grouped by day. Deduplicates — safe to run repeatedly. After backfill, curate main.md — the script seeds placeholders that you should replace with real content.