contextgit 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +87 -27
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -16,46 +16,74 @@ That's it. `init` registers the MCP server, updates CLAUDE.md with session instr
16
16
 
17
17
  ## How it works
18
18
 
19
- ContextGit stores structured context commits alongside your git history. Each commit captures what was done, what was decided, and what questions remain open.
19
+ Git records what changed at each commit. It does not record *why* — the decision behind the change, the approach you rejected, the question the change left open. That intent lives only in the head of whoever made the commit, and it evaporates when the session ends.
20
+
21
+ ContextGit stores that missing layer. Every context save is **bound to a git commit**. The commit is a snapshot of the code; the save bound to it is a snapshot of the intent. Together they let anyone — a teammate, or you in three weeks — pull the repo at any commit and reconstruct *both*: what the code was, and what the thinking was.
20
22
 
21
23
  ```
22
- Session 1: Agent builds auth module → saves context commit
23
- Session 2: Agent loads snapshot → knows auth is done → starts on the next task
24
+ Session 1: Agent builds auth module, commits → saves intent bound to that commit
25
+ Session 2: Agent loads the snapshot → knows auth is done, knows why it was
26
+ built that way → starts on the next task
24
27
  ```
25
28
 
29
+ The save's job is not to repeat the diff (git already has that). It carries what the diff cannot show: decisions, abandoned approaches, open questions, and the next concrete task.
30
+
26
31
  ## What the agent sees
27
32
 
28
33
  When an agent calls `project_memory_load`, it gets a snapshot like this:
29
34
 
30
35
  ```
31
- ## Project State
32
- Auth module complete. API routes tested. Database schema finalized.
33
- Implementing payment integration. Stripe SDK configured.
36
+ ## Git
37
+ Branch: feature/payments | HEAD: a1b2c3d4 | 47 commits
34
38
 
35
- ## Recent Activity
36
- - [2026-03-20T08:33:44Z] "Payment webhook handler done" by solo via claude-code
37
- - [2026-03-20T07:15:22Z] "Stripe SDK integration" by solo via claude-code
38
- - [2026-03-19T16:42:11Z] "Auth module complete" by solo via claude-code
39
+ ## Plan
40
+ [a1b2c3] ▸ Phase 1 — Payments [1/3 done]
41
+ [d4e5f6] ✓ Stripe SDK integration
42
+ [g7h8i9] → Webhook handler ← next
43
+ [j1k2l3] ○ Invoice PDF generation
39
44
 
40
45
  ## Open Threads
41
- - [FREE] Need to add rate limiting to payment endpoints
42
- - [CLAIMED by studio-mcp-agent] Build invoice PDF generation
43
- - [FREE] Decide on webhook retry strategy
46
+ - [m4n5o6] [FREE] Need to add rate limiting to payment endpoints (opened 5/21/2026, interactive)
47
+ - [p7q8r9] [FREE] Decide on webhook retry strategy (opened 5/19/2026, interactive)
48
+ (+3 stale, +1 expired-watch — call project_memory_threads to view)
49
+
50
+ ## Recent Activity
51
+ - [2026-05-22T08:33:44Z] "Payment webhook handler done" by solo via claude-code (interactive)
52
+ - [2026-05-22T07:15:22Z] "Stripe SDK integration" by solo via claude-code (interactive)
53
+ - [2026-05-21T16:42:11Z] "Auth module complete" by solo via claude-code (interactive)
44
54
 
45
55
  ## Active Claims
46
- - "Build invoice PDF generation" claimed by studio-mcp-agent (2h TTL)
56
+ (none)
47
57
  ```
48
58
 
49
59
  The agent reads this and knows exactly where the project stands without you saying a word.
50
60
 
61
+ The `## Git` line is read live from git on every load — branch, HEAD, and commit count are never cached. The `## Plan` section is the project's task hierarchy (plan → step → task); the first unfinished task is marked `← next`. The count hint under `## Open Threads` surfaces decayed entries filtered from the default load (stale open threads + expired watch notes) so the agent can drill in with `project_memory_threads` if needed.
62
+
63
+ Each line carries a short 6-character handle (`[a1b2c3]`) — used to close a thread or check off a task in one step, by handle or by subject.
64
+
65
+ ## Two structures: threads and plans
66
+
67
+ ContextGit tracks two different things, and keeps them separate because they have opposite lifecycles:
68
+
69
+ - **Threads** are unresolved questions and things to watch — "decide on the retry strategy", "watch for the rate-limit edge case". A thread is resolved by being *answered*, and it **decays**: an open thread untouched for long enough is archived (recoverably), and a `watch` note expires on a short TTL. This keeps the load free of a graveyard of dead questions.
70
+ - **Plans** are intended work — a plan → step → task hierarchy you check off as you go. A plan node is resolved by being *done*. Planning **never decays**: a planned task does not become irrelevant because time passed; it is either pending or complete.
71
+
72
+ Threads keep the question list honest; plans keep the work list durable.
73
+
51
74
  ## MCP tools
52
75
 
53
76
  These tools are exposed to the agent via MCP. The agent calls them as part of its normal workflow.
54
77
 
55
78
  | Tool | What it does |
56
79
  |------|-------------|
57
- | `project_memory_load` | Load the full project snapshot — what was built, what's decided, open threads, active claims. Call at session start. |
58
- | `project_memory_save` | Save a context commit — what you did, decisions made, open questions. Call before ending a session. |
80
+ | `project_memory_load` | Load the full project snapshot — the plan, live open threads, recent activity, active claims, plus live git facts (HEAD, commit count). Call at session start. Optional `commit_window` (default 5) controls how many recent commits to include. |
81
+ | `project_memory_save` | Save a context commit, bound to the current git commit — decisions made, approaches abandoned, open questions. Call once per commit; the body carries intent, not a paraphrase of the diff. Can open threads, close threads (`closes_threads`), and check off tasks (`completes_tasks`) in the same call. Threads open as `'open'` (committed) or `'watch'` (a TTL-expiring reminder). |
82
+ | `project_memory_plan` | Create or update the plan hierarchy — lay out a whole plan → step → task tree, or update one node's status (`pending` / `in_progress` / `done`). |
83
+ | `project_memory_plans` | Read the plan tree. `--completed` shows finished plans; `--plan <handle>` drills into one. |
84
+ | `project_memory_threads` | List threads with `filter='stale' \| 'expired-watch' \| 'live' \| 'all' \| 'archived'`. Close a thread with `close=<handle>` or `close_subject=…`; restore an archived thread with `restore=<handle>`; bulk-restore everything archived as `stale-age` or `stale-distance` with `restore_all_stale=true` (recovery primitive for the decay calibration). |
85
+ | `project_memory_retrieve` | Windowed scroll-back. `tier='commits' \| 'trace'`, `window` (default 10), `offset` (default 0). The way to read past the load's recent-commits window or to read the trace tier. |
86
+ | `project_memory_trace` | Record a step-level reasoning note in the fine tier — decisions considered and rejected, dead ends. Pull-only: NEVER appears in `project_memory_load` output. |
59
87
  | `context_search` | Semantic + full-text search over past context commits. |
60
88
  | `project_task_claim` | Claim a task so other agents skip it. Claims auto-expire after 2 hours. |
61
89
  | `project_task_unclaim` | Release a claimed task. |
@@ -64,17 +92,49 @@ These tools are exposed to the agent via MCP. The agent calls them as part of it
64
92
 
65
93
  ## CLI commands
66
94
 
95
+ Most day-to-day work happens through the MCP tools; the CLI is for setup, diagnostics, and operations the MCP server doesn't surface.
96
+
97
+ **Setup + diagnostics**
98
+
99
+ ```bash
100
+ contextgit init # Initialize ContextGit in this project (registers MCP, updates CLAUDE.md)
101
+ contextgit init --hooks # Same, plus install git hooks to auto-capture context on every git commit
102
+ contextgit doctor # Check ContextGit setup and diagnose issues
103
+ ```
104
+
105
+ **Context operations**
106
+
107
+ ```bash
108
+ contextgit commit "message" # Record a context commit
109
+ contextgit context # Print the current project context snapshot
110
+ contextgit log # List context commits for the current branch
111
+ contextgit status # Show current ContextGit status
112
+ contextgit search "query" # Full-text search across context commits
113
+ ```
114
+
115
+ **Branches + multi-agent claims**
116
+
117
+ ```bash
118
+ contextgit branch <name> # Create a new context branch
119
+ contextgit merge <id> # Merge a context branch into the current branch
120
+ contextgit claim "task" # Claim a task so other agents skip it (auto-expires after 2h)
121
+ contextgit unclaim <id> # Release a previously claimed task
122
+ ```
123
+
124
+ **Remote sync (Supabase or self-hosted API)**
125
+
126
+ ```bash
127
+ contextgit set-remote # Configure remote push/pull target
128
+ contextgit remote-show # Show remote configuration and connection status
129
+ contextgit push # Push local context commits to the remote
130
+ contextgit pull # Pull context commits from the remote
131
+ ```
132
+
133
+ **Self-hosted API server**
134
+
67
135
  ```bash
68
- contextgit init # Initialize contextgit in current project
69
- contextgit init --hooks # Initialize with git hooks
70
- contextgit commit "message" # Write a context commit
71
- contextgit status # Show current project state
72
- contextgit search "query" # Search past commits
73
- contextgit claim "task" # Claim a task
74
- contextgit unclaim <id> # Release a claim
75
- contextgit branch <name> # Create a context branch
76
- contextgit merge <id> # Merge a context branch
77
- contextgit serve # Start the REST API server
136
+ contextgit serve # Start the ContextGit REST API server
137
+ contextgit keygen # Generate an API key for securing the server
78
138
  ```
79
139
 
80
140
  ## Architecture
@@ -115,7 +175,7 @@ Project config lives at `.contextgit/config.json`:
115
175
 
116
176
  ## Current status
117
177
 
118
- This is an early-stage tool. It works for solo developers using Claude Code across one or more machines. The core memory layer is solid — context commits, branches, threads, search, and snapshots all work.
178
+ Early-stage but solid for solo developers using Claude Code across one or more machines. As of 0.2.0 the memory layer is structured into three tiers — a live roadmap, commit-bound context saves, and a pull-only reasoning trace — with a plan hierarchy, automatic thread decay, and windowed retrieval. See [CHANGELOG.md](./CHANGELOG.md) for the full 0.2.0 changes.
119
179
 
120
180
  ## Known limitations
121
181
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "contextgit",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "contextgit": "./bin/run.js",
@@ -33,10 +33,10 @@
33
33
  "typecheck": "tsc --noEmit"
34
34
  },
35
35
  "dependencies": {
36
- "@contextgit/core": "0.2.0",
37
- "@contextgit/store": "0.2.0",
38
- "@contextgit/api": "0.2.0",
39
- "@contextgit/mcp": "0.2.0",
36
+ "@contextgit/core": "0.2.1",
37
+ "@contextgit/store": "0.2.1",
38
+ "@contextgit/api": "0.2.1",
39
+ "@contextgit/mcp": "0.2.1",
40
40
  "@oclif/core": "^3.27.0",
41
41
  "nanoid": "^5.0.0",
42
42
  "simple-git": "^3.27.0"