infinitecontex 0.3.1

Local-first project memory for AI coding workflows.

Quick Start · Why It Exists · Commands · Docs

What It Does

infinitecontex captures the working memory around a software project: repository structure, git state, diffs, runtime signals, decisions, active tasks, pinned files, and restore prompts. It stores that state locally in .infctx/ so a developer or coding agent can recover context without rereading the whole repository from scratch.

Current version: 0.3.1

repo + git + chat + intent
        |
        v
  infctx snapshot
        |
        v
.infctx memory store
        |
        +--> agent handoff files
        +--> restore prompts
        +--> searchable history
        +--> snapshot diffs

Why It Exists

Modern coding workflows lose context constantly: terminal output scrolls away, decisions live in chat, diffs only show the present moment, and agents often restart without the reasoning trail that got the project here. Infinite Context turns that working state into durable, inspectable memory.

Quick Start

Install the CLI:

uv tool install infinitecontex
infctx --version

Run from source during development:

uv sync --extra dev
uv run infctx --help

Initialize memory for a project:

uv run infctx init
uv run infctx snapshot --goal "stabilize the CLI release"
uv run infctx status

Work from outside the target repo:

uv run infctx --project-root /path/to/repo snapshot --goal "continue current work"

Daily Workflow

1. Capture The Current State

uv run infctx snapshot --goal "ship the next release"

This records a structured view of the project and refreshes the agent-facing files in .infctx/agents/.

2. Review Memory

uv run infctx status
uv run infctx snapshots --limit 10
uv run infctx show-snapshot

Use these commands to inspect the latest goal, active tasks, pins, recent commits, and snapshot metadata.

3. Compare Work Over Time

uv run infctx compare-snapshots

By default, this compares the latest two snapshots and highlights changed files, task changes, issue changes, and metric deltas.

4. Generate A Handoff Prompt

uv run infctx prompt --mode generic-agent-restore --token-budget 1200

Use the generated prompt when you need a compact restore brief for another model, agent, or session.

5. Run A Live Session

uv run infctx session --goal "refactor restore flow"

session takes an immediate snapshot, watches filtered project changes, skips noisy .infctx/ updates, and refreshes memory as work progresses.

Commands

Global options:

infctx --project-root /path/to/repo status
infctx --version
infctx --help

Generated State

Infinite Context keeps generated files inside .infctx/:

.infctx/
  agents/
    architecture.md
    behavioral.md
    decisions.md
    instructions.md
    overview.md
    recent_changes.md
  metadata/
    state.db
  prompts/
  snapshots/
  working_set/

The most useful files for agents are in .infctx/agents/. They are regenerated from snapshots and are safe to read before making changes.

Configuration

Apply the included Python-oriented preset:

uv run infctx config --set-file config/default.json

The global root option works before the command:

uv run infctx --project-root /path/to/repo config --set-file config/default.json

Development

uv sync --extra dev
uv run ruff check .
uv run mypy src
uv run pytest
uv build

The current local validation suite reports:

• 78 tests passing
• 95% total coverage
• 100% coverage for src/infinitecontex/cli.py

Documentation

Release Notes

See CHANGELOG.md for release history. The 0.3.1 release adds the global --project-root option, removes stale external packaging, simplifies CI, and expands CLI coverage.

License

MIT. See LICENSE.