contextgit 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,130 @@
+# ContextGit
+
+Every time you start a new session with an AI coding agent, it starts from zero. It doesn't know what was built yesterday, what decisions were made, or what's left to do. You spend the first 10 minutes of every session re-explaining your project. ContextGit fixes this — it gives your agents a persistent memory layer that survives across sessions, branches, and machines.
+
+## Install
+
+```bash
+npm install -g contextgit
+cd your-project
+contextgit init
+```
+
+> **Restart Claude Code** (or any MCP client) after running `init` for the MCP server to take effect.
+
+That's it. `init` registers the MCP server, updates CLAUDE.md with session instructions, and installs Claude Code hooks. Start a new session — the agent calls `project_memory_load` automatically and picks up exactly where the last session left off.
+
+## How it works
+
+ContextGit stores structured context commits alongside your git history. Each commit captures what was done, what was decided, and what questions remain open.
+
+```
+Session 1: Agent builds auth module → saves context commit
+Session 2: Agent loads snapshot → knows auth is done → starts on the next task
+```
+
+## What the agent sees
+
+When an agent calls `project_memory_load`, it gets a snapshot like this:
+
+```
+## Project State
+Auth module complete. API routes tested. Database schema finalized.
+
+## Current Branch: Context: main
+Implementing payment integration. Stripe SDK configured.
+
+## Recent Activity
+- [2026-03-20T08:33:44Z] "Payment webhook handler done" by solo via claude-code
+- [2026-03-20T07:15:22Z] "Stripe SDK integration" by solo via claude-code
+- [2026-03-19T16:42:11Z] "Auth module complete" by solo via claude-code
+
+## Open Threads
+- [FREE] Need to add rate limiting to payment endpoints
+- [CLAIMED by studio-mcp-agent] Build invoice PDF generation
+- [FREE] Decide on webhook retry strategy
+
+## Active Claims
+- "Build invoice PDF generation" claimed by studio-mcp-agent (2h TTL)
+```
+
+The agent reads this and knows exactly where the project stands without you saying a word.
+
+## MCP tools
+
+These tools are exposed to the agent via MCP. The agent calls them as part of its normal workflow.
+
+| Tool | What it does |
+|------|-------------|
+| `project_memory_load` | Load the full project snapshot — what was built, what's decided, open threads, active claims. Call at session start. |
+| `project_memory_save` | Save a context commit — what you did, decisions made, open questions. Call before ending a session. |
+| `context_search` | Semantic + full-text search over past context commits. |
+| `project_task_claim` | Claim a task so other agents skip it. Claims auto-expire after 2 hours. |
+| `project_task_unclaim` | Release a claimed task. |
+| `project_memory_branch` | Create a context branch for experimental work. |
+| `project_memory_merge` | Merge a context branch back into the parent. |
+
+## CLI commands
+
+```bash
+contextgit init              # Initialize contextgit in current project
+contextgit init --hooks      # Initialize with git hooks
+contextgit commit "message"  # Write a context commit
+contextgit status            # Show current project state
+contextgit search "query"    # Search past commits
+contextgit claim "task"      # Claim a task
+contextgit unclaim <id>      # Release a claim
+contextgit branch <name>     # Create a context branch
+contextgit merge <id>        # Merge a context branch
+contextgit serve             # Start the REST API server
+```
+
+## Architecture
+
+Monorepo with strict dependency ordering:
+
+```
+packages/
+  core/     → Types, snapshot formatter, embedding service, context engine
+  store/    → Storage interface, LocalStore (SQLite), RemoteStore, SupabaseStore
+  mcp/      → MCP server (stdio transport, launched by Claude Code)
+  cli/      → CLI commands (oclif)
+  api/      → REST API (Express)
+```
+
+**Local storage:** SQLite via better-sqlite3. One DB per project at `~/.contextgit/projects/<id>.db`.
+
+**Remote storage:** Optional Supabase (Postgres + pgvector) for cross-machine sync and team use.
+
+**Embeddings:** Local all-MiniLM-L6-v2 (384 dimensions, no API key needed) for semantic search.
+
+## Configuration
+
+Project config lives at `.contextgit/config.json`:
+
+```json
+{
+  "project": "my-project",
+  "projectId": "unique-id",
+  "store": "local",
+  "agentRole": "solo",
+  "workflowType": "interactive",
+  "autoSnapshot": false,
+  "snapshotInterval": 10,
+  "embeddingModel": "local"
+}
+```
+
+## Current status
+
+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.
+
+## Known limitations
+
+- No automatic context merge when git branches are merged (manual `project_memory_merge` required)
+- No integration with external boards (Linear, Jira, GitHub Issues)
+- Semantic search requires the embedding model to download on first use (~23MB)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextgit",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "bin": {
     "contextgit": "./bin/run.js",
@@ -15,11 +15,28 @@
     "dist",
     "bin"
   ],
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "memory",
+    "context",
+    "git",
+    "mcp",
+    "claude-code",
+    "llm",
+    "persistent-memory"
+  ],
+  "description": "Persistent memory layer for AI agent workflows",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "@contextgit/core": "0.1.5",
-    "@contextgit/store": "0.1.5",
-    "@contextgit/api": "0.1.5",
-    "@contextgit/mcp": "0.1.5",
+    "@contextgit/core": "0.1.7",
+    "@contextgit/store": "0.1.7",
+    "@contextgit/api": "0.1.7",
+    "@contextgit/mcp": "0.1.7",
     "@oclif/core": "^3.27.0",
     "nanoid": "^5.0.0",
     "simple-git": "^3.27.0"
@@ -27,9 +44,5 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit"
   }
-}
+}