Local-first project memory for AI coding workflows.
Quick Start · Why It Exists · Commands · Docs
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
| Local memory | Agent handoff | Snapshot diffing | Restore prompts |
|---|---|---|---|
SQLite and project files under .infctx/ |
Regenerated Markdown briefs for coding agents | Compare goals, files, tasks, issues, and metrics | Compact prompts for resuming work |
repo + git + chat + intent
|
v
infctx snapshot
|
v
.infctx memory store
|
+--> agent handoff files
+--> restore prompts
+--> searchable history
+--> snapshot diffs
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.
| Need | Infinite Context gives you |
|---|---|
| Resume work after an interruption | Snapshot history and restore prompts |
| Hand off to another agent | Regenerated .infctx/agents/*.md files |
| Understand what changed | Snapshot-to-snapshot comparisons |
| Preserve decisions | note, decisions, and chat ingestion |
| Keep important files visible | pin, pins, and unpin |
| Stay local-first | SQLite and project files under .infctx/ |
Install the CLI:
uv tool install infinitecontex
infctx --versionRun from source during development:
uv sync --extra dev
uv run infctx --helpInitialize memory for a project:
uv run infctx init
uv run infctx snapshot --goal "stabilize the CLI release"
uv run infctx statusWork from outside the target repo:
uv run infctx --project-root /path/to/repo snapshot --goal "continue current work"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/.
uv run infctx status
uv run infctx snapshots --limit 10
uv run infctx show-snapshotUse these commands to inspect the latest goal, active tasks, pins, recent commits, and snapshot metadata.
uv run infctx compare-snapshotsBy default, this compares the latest two snapshots and highlights changed files, task changes, issue changes, and metric deltas.
uv run infctx prompt --mode generic-agent-restore --token-budget 1200Use the generated prompt when you need a compact restore brief for another model, agent, or 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.
| Command | Purpose |
|---|---|
infctx init |
Create .infctx/ and initialize local metadata |
infctx snapshot |
Capture a one-off project memory snapshot |
infctx session |
Start a live capture session |
infctx watch |
Compatibility alias for session |
infctx status |
Show latest memory state, pins, tasks, and commits |
infctx snapshots |
List recent snapshots |
infctx show-snapshot |
Inspect one snapshot in detail |
infctx compare-snapshots |
Compare two captured memory states |
infctx prompt |
Generate a compact restore prompt |
infctx restore |
Validate restore state against a snapshot |
infctx ingest-chat |
Ingest transcript-derived intent and decisions |
infctx note |
Save an architectural or workflow decision |
infctx decisions |
List recent decisions |
infctx pin / pins / unpin |
Manage high-priority context files |
infctx search |
Search local memory |
infctx diff-summary |
Summarize current uncommitted changes |
infctx config |
Read or apply project configuration |
infctx doctor |
Run integrity and dependency diagnostics |
infctx export / import |
Move local memory between machines |
infctx cleanup |
Prune old snapshots and compact storage |
infctx setup-agent |
Wire Cursor, Claude, Copilot, or Windsurf to .infctx/agents/ |
Global options:
infctx --project-root /path/to/repo status
infctx --version
infctx --helpInfinite 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.
Apply the included Python-oriented preset:
uv run infctx config --set-file config/default.jsonThe global root option works before the command:
uv run infctx --project-root /path/to/repo config --set-file config/default.jsonuv sync --extra dev
uv run ruff check .
uv run mypy src
uv run pytest
uv buildCurrent local QC:
78tests passing95%total coverage100%coverage forsrc/infinitecontex/cli.pyuv buildproduces the wheel and source archive
| Topic | File |
|---|---|
| Product overview | docs/overview.md |
| Architecture | docs/architecture.md |
| CLI reference | docs/cli-reference.md |
| CLI behavior contract | docs/cli-behavior-contract.md |
| Configuration | docs/config-reference.md |
| Data model | docs/data-model-reference.md |
| Restore pipeline | docs/restore-pipeline.md |
| Security and privacy | docs/security-privacy.md |
| Testing strategy | docs/testing-strategy.md |
| Troubleshooting | docs/troubleshooting.md |
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.
MIT. See LICENSE.