Metadata-Version: 2.5
Name: gcontext-ai
Version: 1.1.0
Summary: A standard for a context/ folder in your repo, plus a small CLI.
Project-URL: Homepage, https://github.com/bleak-ai/gcontext
Project-URL: Repository, https://github.com/bleak-ai/gcontext
Author: bleak-ai
License: MIT
License-File: LICENSE
Keywords: agents,ai,context,mcp,state
Requires-Python: >=3.11
Requires-Dist: certifi
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# gcontext

gcontext is a folder standard. It gives an AI agent a memory of your
project.

## The problem

An AI agent forgets everything between sessions. You repeat the same
facts. The agent makes the same mistakes. The usual fix is one large
notes file. That file grows. Nobody reads it. The agent stops finding
facts in it.

## The idea

gcontext replaces that file with a folder named `context/`. The agent
writes each durable fact into `context/`. Each fact goes into the file
of its subject. Files that share a name go into a folder with that
name. The tree grows from the content. You do not design it in
advance.

One rule decides where a fact goes: a path is a chain of common
denominators. A folder name is what all its entries share. A file
holds all the facts about one subject.

From that rule follow three tests:

- A thing gets its own file when three facts are about it.
- Two files that share a name get a folder with that name.
- At every level, two entries always share something. When what they
  share is smaller than the folder they sit in, a folder is missing.

Read `docs/principles.md` for the idea on one page. Read
`docs/standard.md` for the complete standard. That file is the whole
standard. There is no other rule file.

## What you get

After you install gcontext in a project, three things happen.

1. Journal. A hook writes facts into `context/journal/` every ten
   turns. The hook gives no report. `/add-to-context` reviews the
   journal and promotes useful facts into `context/project/`. You
   say "apply" one time.
2. Track. Your status line shows one line after every turn. It tells
   you how many facts and folders the agent added since the last
   structure check. The line is green, amber, or red.
3. Check. When the line is red, you run `/check-structure`. The agent
   proposes the smallest tree that passes the rules. You say
   "apply". The agent moves the content. The counter goes back to
   zero.

A git hook stops each commit that breaks the structure.

## How to start

You need `uv` (https://docs.astral.sh/uv) and Claude Code.

1. Install the CLI.

   ```bash
   uv tool install gcontext-ai
   ```

2. Go to the root of your project. Run init.

   ```bash
   gcontext init
   ```

   init writes these files. It does not overwrite a file that exists.

   - `context/index.md` and `context/project/index.md`: the entry
     points of the memory.
   - `context/journal/`: raw facts that wait for review.
   - `context/system/rules.md`: the standard.
   - `context/system/log.md`: the history of structure checks.
   - `context/system/scripts/`: the scripts listed below.
   - `.claude/commands/`: the three Claude Code commands `/save`,
     `/add-to-context`, and `/check-structure`.
   - `.claude/settings.json`: the Stop hook that writes journal facts.
   - `CLAUDE.md`: two lines that tell the agent to read the memory
     and to follow the rules.

   init also sets `git config core.hooksPath` to the bundled hooks
   folder. Then it runs the structure check.

3. Add the tracker to your Claude Code status line. init prints the
   command. It is:

   ```bash
   uv run --no-project python3 context/system/scripts/track-context-changes.py . --color
   ```

4. Work as usual. Ask the agent questions. Let it do tasks. The hook
   writes journal facts on its own. Type `/save` when you want a
   direct save now. Type `/add-to-context` to review journal facts.

5. When the status line is red, type `/check-structure`. Read the
   proposal. Type "apply".

## What each script does

init writes all scripts to `context/system/scripts/`. Run each one
with `uv run`.

### sync-index-files.py

This script keeps every `index.md` correct. Each folder has one
`index.md`. The index has a hand-written purpose line at the top and
a generated list of entries below a marker. The script copies the
purpose line of each entry into the parent index.

- `--write` regenerates every index list.
- `--check` reports problems and exits with code 1. It reports: a
  folder without `index.md`, a name with an uppercase letter, a file
  without a purpose line, an index entry that names a missing entry,
  an existing entry that the index omits, a `TODO(describe)`
  placeholder, and a pointer line whose target does not exist.

The agent runs `--write` after every save. The pre-commit hook runs
`--check`.

### track-context-changes.py

This script prints one line for the status line. It counts the fact
lines and the folders under `context/project/`. It also counts journal
sessions since the last journal review. It compares the counts with
the last matching lines in `context/system/log.md`.

Output example:

```text
context: +4 facts, +0 folders since the structure check (2026-09-06), 3 sessions to review, run /add-to-context
```

The `--color` flag adds a color. Green means fewer than 10 new facts
and fewer than 3 new folders. Amber means fewer than 20 facts and
fewer than 5 folders. Red means more. The line tells you what to do
next. Journal sessions are amber at 3 and red at 6. The worse level
sets the line color. The script always exits with code 0.

### journal-every-n-turns.py

This script is a Claude Code Stop hook. Claude Code runs it after
every assistant turn. The script counts the turns of the session.
On every tenth turn it tells the agent to append facts to one file
under `context/journal/`. The script supplies the date, session, time,
and next entry number. The agent uses one Write or Edit call. It does
not report the write or sync indexes. Then it continues its task.

The script never triggers itself. It exits without output when a
hook turn is already in progress. Set the environment variable
`GCONTEXT_SAVE_EVERY` to change the interval.

### journal-review.py

This script finds journal facts that need review. `--marker` prints
the last journal review time from `context/system/log.md`. `--list`
prints changed journal files and session transcripts as JSON. Use
`--since <iso>` to set a different start time.

`--condense <transcript>` prints the useful text from one transcript.
Use `--after <iso>` to omit older records. It keeps user text and
assistant text. It reduces each tool call to its name and first
argument. It drops tool results, sidechain records, and thinking.

### githooks/pre-commit

This shell script is the git pre-commit hook. It does two checks.

1. It looks for structure changes in the staged files: a deleted
   markdown file, a renamed markdown file, or a new markdown file
   below the second level of `context/project/`. If it finds one
   and `context/system/log.md` is not in the commit, the commit
   stops. A structure change needs one line in the log.
2. It runs `sync-index-files.py --check`. If the check fails, the
   commit stops.

init enables the hook with `git config core.hooksPath`. To bypass it
once, commit with `--no-verify` and tell the owner why.

### rules_config.py

This module reads optional rule toggles for `sync-index-files.py`.
The standard does not use toggles at the moment. The module returns
no toggles when no toggle file exists.

## The three commands

- `/save`: the agent collects the durable facts of the session and
  writes each one into the file of its subject. It does not ask for
  approval. It reports one line per file it changed.
- `/add-to-context`: the agent reviews journal files and session
  transcripts. It proposes each new or changed fact and its target
  path. It waits for "apply". Then it writes the approved facts and
  records the review time.
- `/check-structure`: the agent reads every file under
  `context/project/`, applies the file test, the folder test, and
  the pair test, and proposes the target tree. It waits for
  "apply". Then it moves the content, regenerates the indexes, and
  appends a structure check line to `log.md`.

## The CLI

- `gcontext init [dir]`: write `context/` from the bundled standard.
- `gcontext check [dir]`: run the structure checks.
- `gcontext serve [dir]`: start the MCP server that exposes
  `context/` to other runtimes. See `docs/mcp.md`.
- `gcontext install <package-folder> [dir]`: install a package into
  `context/packages/`.

See `docs/cli.md` for arguments and exit codes.

## What it is not

- Not a database. Not a vector store. Plain markdown in git.
- Not a config file the agent reads once. The agent writes there too.
- Not tied to one tool. The rules are one file. Any agent that can
  read and write files can follow them. The hook and the commands
  are for Claude Code.

## Documentation

- `docs/principles.md`: what gcontext is and why, on one page.
- `docs/standard.md`: the standard, version 1.0.
- `docs/cli.md`: commands, arguments, exit codes.
- `docs/mcp.md`: the MCP server.
- `CHANGELOG.md`: releases.

## License

MIT
