ctxbaton 0.1.0__tar.gz

ctxbaton-0.1.0/.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm show:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(d.get\\(''''exports'''', {}\\), indent=2\\)\\)\")",
+      "Read(//Users/toffe/.npm/_npx/**)",
+      "Read(//Users/toffe/node_modules/**)",
+      "Read(//usr/local/lib/**)",
+      "Bash(npm install:*)",
+      "Bash(npm run:*)",
+      "Bash(node:*)",
+      "Bash(node --experimental-sqlite -e \":*)",
+      "WebFetch(domain:www.anthropic.com)",
+      "WebFetch(domain:openspec.dev)",
+      "WebSearch",
+      "Bash(uv sync:*)",
+      "Bash(rm -f ~/.mcp-memory/memories.db)",
+      "Bash(uv run python -c \":*)",
+      "WebFetch(domain:gist.github.com)",
+      "WebFetch(domain:gist.githubusercontent.com)",
+      "Bash(uv run:*)",
+      "Bash(uv tool:*)",
+      "Read(//Users/toffe/dev/ai/graceful.ai/**)",
+      "Bash(mv mcp-memory:*)",
+      "Bash(unicontext:*)",
+      "WebFetch(domain:opencode.ai)",
+      "WebFetch(domain:developers.openai.com)",
+      "Bash(ctxbaton --help)",
+      "Bash(ctxbaton context:*)",
+      "Bash(uv build:*)"
+    ]
+  }
+}

ctxbaton-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Distribution
+*.whl
+*.tar.gz
+
+# DB files — never commit the memory store
+*.db
+*.db-wal
+*.db-shm
+
+# Snapshots — user data, not source
+snapshots/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Env
+.env
+.env.local

ctxbaton-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 melonkernel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctxbaton-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: ctxbaton
+Version: 0.1.0
+Summary: Pass context between AI agents like a relay baton — persistent memory, snapshots, and semantic search across sessions
+Project-URL: Homepage, https://github.com/melonkernel/ctxbaton
+Project-URL: Repository, https://github.com/melonkernel/ctxbaton
+Project-URL: Issues, https://github.com/melonkernel/ctxbaton/issues
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,codex,context,mcp,memory,opencode
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Description-Content-Type: text/markdown
+
+# ctxbaton
+
+> Pass context between AI agents like a relay baton.
+
+When you switch agents mid-project — because you ran out of tokens, changed tools, or just opened a new session — ctxbaton makes sure nothing is lost. Every agent picks up exactly where the last one stopped.
+
+## How it works
+
+A lightweight hook fires after every agent turn and saves a snapshot: the current git hash, todo state diff, and transcript path. No tokens spent. No agent cooperation required. It just happens.
+
+When you resume — in the same agent or a different one — run:
+
+```bash
+ctxbaton context    # what are we building, what's open, what was decided
+ctxbaton replay     # what changed since I was last here
+```
+
+## Install
+
+```bash
+# Install globally
+uv tool install ctxbaton
+
+# Wire up the automatic Stop hook (Claude Code)
+ctxbaton hooks install
+```
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+## Commands
+
+```bash
+ctxbaton context              # full project context — spec, todos, handoff, decisions
+ctxbaton replay               # what changed since last snapshot (git diff + todo changes)
+ctxbaton replay --since 2h    # what changed in the last 2 hours
+ctxbaton search "auth"        # semantic search across all memories
+
+ctxbaton todo list            # open tasks
+ctxbaton todo done <id>       # mark a task done
+ctxbaton todo start <id>      # mark a task in progress
+
+ctxbaton memory save --type decision "use JWT over sessions because..."
+ctxbaton memory save --type handoff  "stopped mid-auth, next: refresh tokens"
+ctxbaton memory save --type spec     "build a REST API with FastAPI"
+ctxbaton memory save --type todo     "add rate limiting"
+
+ctxbaton snapshot list        # full snapshot history with git hashes
+ctxbaton hooks install        # install Claude Code Stop hook
+ctxbaton serve                # start as MCP server
+```
+
+## Memory types
+
+| Type | Purpose |
+|------|---------|
+| `spec` | The current goal or plan |
+| `todo` | A task with status (pending / in_progress / done) |
+| `decision` | An architecture or design choice with rationale |
+| `handoff` | State snapshot when switching agents or sessions |
+| `progress` | What has been completed |
+| `general` | Anything else |
+
+## Cross-agent continuity
+
+ctxbaton is agent-agnostic. Claude Code, OpenCode, Codex, Cursor — they all call the same CLI and write to the same store.
+
+Each project gets its own isolated DB at:
+```
+~/.ctxbaton/projects/-Users-you-dev-myproject/memories.db
+```
+
+The path mirrors the project directory (same convention as Claude Code's own memory files), so there's no config needed — open a project, run `ctxbaton context`, done.
+
+## Automatic snapshots
+
+Install the Stop hook once:
+
+```bash
+ctxbaton hooks install
+```
+
+After that, every time an agent finishes a turn, ctxbaton saves:
+- The current git hash and branch
+- A diff of what todos changed
+- A reference to the session transcript
+
+No tokens. No agent cooperation. Just a shell script that runs in milliseconds.
+
+## Agent Skills (Claude Code, Codex, Cursor)
+
+ctxbaton ships with a `SKILL.md` that auto-injects project context at session start.
+Copy it to your skills directory:
+
+```bash
+cp skill/SKILL.md ~/.claude/skills/ctxbaton/SKILL.md
+```
+
+Or run the full installer:
+
+```bash
+bash skill/scripts/install.sh
+```
+
+Then use `/ctxbaton` in any session to load context instantly.
+
+## MCP server
+
+```bash
+ctxbaton serve
+```
+
+Register in Claude Code:
+```bash
+claude mcp add ctxbaton -- ctxbaton serve
+```
+
+Or in any MCP-compatible client:
+```json
+{
+  "mcpServers": {
+    "ctxbaton": {
+      "command": "ctxbaton",
+      "args": ["serve"],
+      "env": { "MEMORY_PROJECT": "/path/to/your/project" }
+    }
+  }
+}
+```
+
+## Storage
+
+Memories are stored in SQLite with local embeddings ([BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5), ~40MB, downloaded once). No API keys. Works offline.
+
+## License
+
+MIT — [melonkernel/ctxbaton](https://github.com/melonkernel/ctxbaton)

ctxbaton-0.1.0/README.md

@@ -0,0 +1,136 @@
+# ctxbaton
+
+> Pass context between AI agents like a relay baton.
+
+When you switch agents mid-project — because you ran out of tokens, changed tools, or just opened a new session — ctxbaton makes sure nothing is lost. Every agent picks up exactly where the last one stopped.
+
+## How it works
+
+A lightweight hook fires after every agent turn and saves a snapshot: the current git hash, todo state diff, and transcript path. No tokens spent. No agent cooperation required. It just happens.
+
+When you resume — in the same agent or a different one — run:
+
+```bash
+ctxbaton context    # what are we building, what's open, what was decided
+ctxbaton replay     # what changed since I was last here
+```
+
+## Install
+
+```bash
+# Install globally
+uv tool install ctxbaton
+
+# Wire up the automatic Stop hook (Claude Code)
+ctxbaton hooks install
+```
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+## Commands
+
+```bash
+ctxbaton context              # full project context — spec, todos, handoff, decisions
+ctxbaton replay               # what changed since last snapshot (git diff + todo changes)
+ctxbaton replay --since 2h    # what changed in the last 2 hours
+ctxbaton search "auth"        # semantic search across all memories
+
+ctxbaton todo list            # open tasks
+ctxbaton todo done <id>       # mark a task done
+ctxbaton todo start <id>      # mark a task in progress
+
+ctxbaton memory save --type decision "use JWT over sessions because..."
+ctxbaton memory save --type handoff  "stopped mid-auth, next: refresh tokens"
+ctxbaton memory save --type spec     "build a REST API with FastAPI"
+ctxbaton memory save --type todo     "add rate limiting"
+
+ctxbaton snapshot list        # full snapshot history with git hashes
+ctxbaton hooks install        # install Claude Code Stop hook
+ctxbaton serve                # start as MCP server
+```
+
+## Memory types
+
+| Type | Purpose |
+|------|---------|
+| `spec` | The current goal or plan |
+| `todo` | A task with status (pending / in_progress / done) |
+| `decision` | An architecture or design choice with rationale |
+| `handoff` | State snapshot when switching agents or sessions |
+| `progress` | What has been completed |
+| `general` | Anything else |
+
+## Cross-agent continuity
+
+ctxbaton is agent-agnostic. Claude Code, OpenCode, Codex, Cursor — they all call the same CLI and write to the same store.
+
+Each project gets its own isolated DB at:
+```
+~/.ctxbaton/projects/-Users-you-dev-myproject/memories.db
+```
+
+The path mirrors the project directory (same convention as Claude Code's own memory files), so there's no config needed — open a project, run `ctxbaton context`, done.
+
+## Automatic snapshots
+
+Install the Stop hook once:
+
+```bash
+ctxbaton hooks install
+```
+
+After that, every time an agent finishes a turn, ctxbaton saves:
+- The current git hash and branch
+- A diff of what todos changed
+- A reference to the session transcript
+
+No tokens. No agent cooperation. Just a shell script that runs in milliseconds.
+
+## Agent Skills (Claude Code, Codex, Cursor)
+
+ctxbaton ships with a `SKILL.md` that auto-injects project context at session start.
+Copy it to your skills directory:
+
+```bash
+cp skill/SKILL.md ~/.claude/skills/ctxbaton/SKILL.md
+```
+
+Or run the full installer:
+
+```bash
+bash skill/scripts/install.sh
+```
+
+Then use `/ctxbaton` in any session to load context instantly.
+
+## MCP server
+
+```bash
+ctxbaton serve
+```
+
+Register in Claude Code:
+```bash
+claude mcp add ctxbaton -- ctxbaton serve
+```
+
+Or in any MCP-compatible client:
+```json
+{
+  "mcpServers": {
+    "ctxbaton": {
+      "command": "ctxbaton",
+      "args": ["serve"],
+      "env": { "MEMORY_PROJECT": "/path/to/your/project" }
+    }
+  }
+}
+```
+
+## Storage
+
+Memories are stored in SQLite with local embeddings ([BAAI/bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5), ~40MB, downloaded once). No API keys. Works offline.
+
+## License
+
+MIT — [melonkernel/ctxbaton](https://github.com/melonkernel/ctxbaton)

ctxbaton-0.1.0/SETUP.md

@@ -0,0 +1,125 @@
+# ctxbaton v2
+
+Persistent agent memory with semantic search. One DB per project, stored in
+userspace — mirroring Anthropic's own convention for project-scoped files.
+
+## Requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+## Install
+
+```bash
+uv sync
+```
+
+On first use the embedding model (BAAI/bge-small-en-v1.5, ~40MB) is
+downloaded to `~/.cache/fastembed/` automatically.
+
+## Storage
+
+Each project gets its own DB:
+
+```
+~/.ctxbaton/projects/-Users-you-dev-myproject/memories.db
+```
+
+The path mirrors the project path with `/` replaced by `-`, same convention
+Claude Code uses for its own project files.
+
+Override the project path with the `MEMORY_PROJECT` env var (defaults to cwd).
+
+---
+
+## Register as MCP server
+
+The key is passing `MEMORY_PROJECT` so the server opens the right DB.
+
+### Claude Code (CLI)
+
+Run this from inside your project directory:
+
+```bash
+claude mcp add memory \
+  --env MEMORY_PROJECT=$(pwd) \
+  uv -- --directory /Users/toffe/dev/ai/graceful.ai/ctxbaton run ctxbaton
+```
+
+Or add it to `.claude/settings.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "uv",
+      "args": ["--directory", "/Users/toffe/dev/ai/graceful.ai/ctxbaton", "run", "ctxbaton"],
+      "env": { "MEMORY_PROJECT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "uv",
+      "args": ["--directory", "/Users/toffe/dev/ai/graceful.ai/ctxbaton", "run", "ctxbaton"],
+      "env": { "MEMORY_PROJECT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+### OpenCode
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "memory": {
+        "command": "uv",
+        "args": ["--directory", "/Users/toffe/dev/ai/graceful.ai/ctxbaton", "run", "ctxbaton"],
+        "env": { "MEMORY_PROJECT": "/absolute/path/to/your/project" }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `save_memory` | Save a memory to the current project |
+| `search_memories` | Semantic search, returns results with `_score` |
+| `list_memories` | List by type / status / agent / session |
+| `get_context` | Full snapshot: spec + open todos + handoff + decisions |
+| `update_todo_status` | Mark a todo `pending` / `in_progress` / `done` |
+| `get_memory` | Fetch one memory by ID |
+| `update_memory` | Edit content, summary, type, or tags |
+| `delete_memory` | Delete by ID |
+
+## Memory types
+
+| Type | Purpose |
+|------|---------|
+| `spec` | Current goal or plan |
+| `todo` | Task with status (pending / in_progress / done) |
+| `decision` | Architecture or design choice with rationale |
+| `handoff` | State snapshot when switching agents or sessions |
+| `progress` | What has been completed |
+| `general` | Anything else |
+
+## Cross-agent session continuity
+
+Pass `agent` (e.g. `"claude"`, `"opencode"`) and `session_id` when saving.
+To resume in a different agent, call `get_context()` — it returns the active
+spec, open todos, latest handoff, and recent decisions in one call.

ctxbaton-0.1.0/hooks/stop.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# ctxbaton Stop hook
+# Fires after every Claude turn. Saves a snapshot: git hash, todo diff, transcript path.
+# No tokens required. Runs in milliseconds.
+#
+# Claude Code passes hook data as JSON on stdin:
+#   { "session_id": "...", "cwd": "...", "transcript_path": "...", "hook_event_name": "Stop" }
+
+set -euo pipefail
+
+# Find ctxbaton — prefer project venv, fall back to PATH
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+VENV_BIN="$PROJECT_DIR/.venv/bin/ctxbaton"
+
+if [ -x "$VENV_BIN" ]; then
+  MCP_MEMORY="$VENV_BIN"
+elif command -v ctxbaton &>/dev/null; then
+  MCP_MEMORY="ctxbaton"
+elif command -v uvx &>/dev/null; then
+  MCP_MEMORY="uvx --from $PROJECT_DIR ctxbaton"
+else
+  echo '{"error": "ctxbaton not found"}' >&2
+  exit 0  # don't block Claude on failure
+fi
+
+# Read stdin (hook JSON) and pipe to snapshot save
+# MEMORY_PROJECT tells the CLI which DB to use
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('cwd',''))" 2>/dev/null || echo "")
+export MEMORY_PROJECT="${CWD:-$(pwd)}"
+
+echo "$INPUT" | $MCP_MEMORY snapshot save 2>/dev/null || true
+
+# Always exit 0 — never block Claude
+exit 0

ctxbaton-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "ctxbaton"
+version = "0.1.0"
+description = "Pass context between AI agents like a relay baton — persistent memory, snapshots, and semantic search across sessions"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "agents", "memory", "context", "mcp", "claude", "opencode", "codex"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "fastembed>=0.4.0",
+    "numpy>=1.26.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/melonkernel/ctxbaton"
+Repository = "https://github.com/melonkernel/ctxbaton"
+Issues = "https://github.com/melonkernel/ctxbaton/issues"
+
+[project.scripts]
+ctxbaton = "ctxbaton.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ctxbaton"]
+
+[tool.uv]
+dev-dependencies = []

ctxbaton-0.1.0/skill/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: ctxbaton
+description: >
+  Loads persistent project context at session start. Tracks todos, decisions,
+  handoffs, and git state automatically. Use this to resume work across agents
+  and sessions without losing context.
+argument-hint: "[query]"
+allowed-tools: Bash(ctxbaton *)
+---
+
+## Project context
+!`ctxbaton context`
+
+## Instructions
+
+You now have full project context loaded above. Use it to resume work immediately.
+
+When starting work on a task, mark it in progress:
+`ctxbaton todo start <id>`
+
+When finishing a task:
+`ctxbaton todo done <id>`
+
+When making an architecture or design decision:
+`ctxbaton memory save --type decision "<what was decided and why>"`
+
+When ending a session or handing off to another agent:
+`ctxbaton memory save --type handoff "<what you were doing, what's next, any blockers>"`
+
+To resume after a break or unexpected session end:
+`ctxbaton replay --since 2h`
+
+To search past decisions and context:
+`ctxbaton search "<query>"`
+
+To add a new todo:
+`ctxbaton memory save --type todo "<task>"`

ctxbaton-0.1.0/skill/scripts/install.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# ctxbaton skill installer
+# Installs the CLI globally and wires up the Stop hook for automatic snapshots.
+#
+# Usage: bash install.sh
+
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROJECT_DIR="$(dirname "$SKILL_DIR")"
+
+echo "Installing ctxbaton..."
+
+# Install CLI globally
+if command -v uv &>/dev/null; then
+  uv tool install --editable "$PROJECT_DIR"
+else
+  echo "Error: uv is required. Install from https://docs.astral.sh/uv/" >&2
+  exit 1
+fi
+
+# Install Stop hook
+ctxbaton hooks install
+
+# Copy skill to Claude Code skills directory
+CLAUDE_SKILLS="$HOME/.claude/skills/ctxbaton"
+mkdir -p "$CLAUDE_SKILLS"
+cp -r "$SKILL_DIR/." "$CLAUDE_SKILLS/"
+echo "✓ Skill installed → $CLAUDE_SKILLS"
+
+echo ""
+echo "Done. ctxbaton is active."
+echo "  Run 'ctxbaton context' to verify."
+echo "  Use '/ctxbaton' in Claude Code to load project context."