ramets 0.3.0__tar.gz

ramets-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish Panneer Selvam
+
+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.

ramets-0.3.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: ramets
+Version: 0.3.0
+Summary: Per-branch AI coding context — delta-encoded knowledge graphs, decision tracking, and Obsidian visualization. Your codebase is one organism. Each branch is a ramet.
+Author: Harish Panneer Selvam
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/panne027/ramets
+Project-URL: Repository, https://github.com/panne027/ramets
+Project-URL: Issues, https://github.com/panne027/ramets/issues
+Keywords: ai,coding,context,git,worktree,knowledge-graph,obsidian,claude,cursor,codex,branch,delta
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.0
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: graphifyy>=0.3.10
+Requires-Dist: jinja2>=3.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: fastmcp>=0.1; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: mcp>=1.0; extra == "all"
+Requires-Dist: fastmcp>=0.1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# ramets
+
+**Per-branch AI coding context** — delta-encoded knowledge graphs, decision tracking, and Obsidian visualization.
+
+*Your codebase is one organism. Each branch is a ramet.*
+
+[![CI](https://github.com/panne027/ramets/actions/workflows/ci.yml/badge.svg)](https://github.com/panne027/ramets/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ramets)](https://pypi.org/project/ramets/)
+[![Python](https://img.shields.io/pypi/pyversions/ramets)](https://pypi.org/project/ramets/)
+
+Named after [Pando](https://en.wikipedia.org/wiki/Pando_(tree)) (*Populus tremuloides*), the world's largest organism — a single aspen clone where individual trunks (ramets) share one root system (genet).
+
+---
+
+## The Problem
+
+AI coding assistants (Claude Code, Cursor, Codex) waste enormous tokens re-reading your codebase every session:
+
+| Without ramets | With ramets | Savings |
+|---|---|---|
+| Read knowledge graph: **212K tokens** | Session summary injection: ~400 tokens | **99.8%** |
+| Re-read files on branch switch: ~50K | Delta summary: ~200 tokens | **99.6%** |
+| "What did we decide?" — grep history: ~10K | `ramets decisions`: ~300 tokens | **97%** |
+| New session, re-explore codebase: ~30K | SessionStart hook: ~500 tokens | **98%** |
+
+LLM providers aren't incentivized to fix this — more tokens means more subscription revenue. So we fix it ourselves.
+
+## Quick Start
+
+```bash
+pip install ramets
+
+cd your-repo
+ramets init          # Build genet, install hooks (~5 seconds)
+ramets query "how does authentication work?"   # ~300 tokens
+ramets status        # Show genet freshness, branch deltas
+ramets summary       # Session context (~400 tokens)
+ramets obsidian      # Generate Obsidian vault for visualization
+```
+
+## How It Works
+
+```
+Genet (shared root)    ──>  base knowledge graph from common ancestor
+  ├── Ramet: main      ──>  0 deltas (is the base)
+  ├── Ramet: feat/auth  ──>  12 deltas (added auth module)
+  ├── Ramet: fix/typo   ──>  2 deltas (renamed function)
+  └── Ramet: feat/api   ──>  28 deltas (new API layer)
+
+Total storage: ~100KB for 400 nodes (ramets codebase itself)
+```
+
+1. **`ramets init`** builds the genet from tree-sitter AST extraction (via [graphify](https://pypi.org/project/graphifyy/))
+2. **Git hooks** fire on every commit/checkout — zero LLM tokens, all local computation
+3. **Claude Code hooks** inject pre-computed summaries at session start (~400 tokens)
+4. **`ramets query`** does keyword + BFS traversal with configurable token budgets
+
+**Git hooks do ALL computation. The LLM only consumes pre-computed results.**
+
+## Features
+
+### Delta-Encoded Knowledge Graphs
+- **Genet**: shared base graph (zlib-compressed, ~80KB)
+- **Ramets**: per-branch deltas — only what changed (add/remove/modify nodes and edges)
+- Concurrent worktree access via SQLite WAL mode
+- Storage: **104KB** for 408 nodes, 837 edges (real measurement on ramets codebase)
+
+### Git Hooks (Zero Token Cost)
+
+| Hook | Trigger | What it does |
+|---|---|---|
+| post-commit | Every commit | Compute branch delta (AST diff vs genet) |
+| post-checkout | Branch switch | Register branch, prep snapshot |
+| post-merge | After pull/merge | Recompute deltas |
+| post-rewrite | After rebase | Rebuild deltas for rewritten commits |
+
+### Claude Code Hooks (Token Savings)
+
+| Hook | Trigger | Tokens saved |
+|---|---|---|
+| SessionStart | Session begins | ~212K (injects 400-token summary instead) |
+| UserPromptSubmit | User sends prompt | ~30-50K (redirects to graph query) |
+| PreToolUse | File read attempted | ~10-50K (gates expensive reads) |
+
+### Decision Tracking
+
+Structured records of "AI suggested X, user chose Y" — not natural language summaries.
+
+```bash
+ramets decide \
+  -q "Which auth strategy?" \
+  -o "JWT:Stateless tokens" \
+  -o "Session cookies:Server-side sessions" \
+  -c 0 \
+  -r "Stateless fits our microservices design" \
+  --category architecture \
+  --confidence 0.85
+
+ramets decisions                        # List active decisions
+ramets decisions -s "auth"              # Full-text search
+ramets decisions --id abc123            # View decision detail
+```
+
+### Obsidian Visualization
+
+```bash
+ramets obsidian                         # Generate vault
+ramets obsidian --open                  # Generate and open in Obsidian
+ramets obsidian --all-branches          # Include all branch layers
+```
+
+Generates a navigable vault with:
+- **Base layer**: Community-colored nodes with `[[wikilinks]]`
+- **Branch delta layers**: Added/modified/removed nodes per branch
+- **Decision notes**: Structured choices with options and rationale
+- **Graph settings**: Community coloring for the graph view
+
+### MCP Server (15 tools)
+
+```bash
+pip install ramets[mcp]
+ramets serve                            # stdio transport
+# Or: claude mcp add ramets -- ramets serve
+```
+
+Tools: `query_graph`, `get_node`, `diff_branches`, `session_summary`, `record_decision`, `list_decisions`, `search_decisions`, `generate_obsidian_vault`, and more.
+
+## Architecture
+
+```
+.ramets/store.db (SQLite, WAL mode)
+├── genet         — shared root graph (compressed blob)
+├── ramets        — materialized per-branch snapshots
+├── ramet_deltas  — delta log per branch
+├── decisions     — structured decision records
+├── decision_edges — decision relationship graph
+├── sessions      — AI session tracking
+└── branches      — branch registry
+```
+
+## CLI Reference
+
+```
+ramets init              Create .ramets/, build genet, install hooks
+ramets build             Full genet rebuild from HEAD
+ramets update            Compute branch delta vs genet (called by hooks)
+ramets status            Genet freshness, ramet count, storage
+ramets query "..."       BFS traversal on current branch graph
+ramets diff feat/a main  Graph diff between branches
+ramets summary           Compact summary for session injection (~400 tokens)
+ramets decide            Record a structured decision
+ramets decisions         List/search decisions for current branch
+ramets obsidian          Generate Obsidian vault with branch layers
+ramets obsidian --open   Generate and open in Obsidian
+ramets serve             Start MCP server (stdio)
+ramets gc                Prune dead ramets, compact DB
+```
+
+## Development
+
+```bash
+git clone https://github.com/panne027/ramets.git
+cd ramets
+pip install -e ".[dev]"
+pytest tests/ -v                         # 70 tests
+ruff check src/ tests/                   # Lint
+ruff format src/ tests/                  # Format
+```
+
+## Requirements
+
+- Python >= 3.10
+- Git repository
+- [graphify](https://pypi.org/project/graphifyy/) (installed as dependency)
+
+## License
+
+MIT

ramets-0.3.0/README.md

@@ -0,0 +1,178 @@
+# ramets
+
+**Per-branch AI coding context** — delta-encoded knowledge graphs, decision tracking, and Obsidian visualization.
+
+*Your codebase is one organism. Each branch is a ramet.*
+
+[![CI](https://github.com/panne027/ramets/actions/workflows/ci.yml/badge.svg)](https://github.com/panne027/ramets/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ramets)](https://pypi.org/project/ramets/)
+[![Python](https://img.shields.io/pypi/pyversions/ramets)](https://pypi.org/project/ramets/)
+
+Named after [Pando](https://en.wikipedia.org/wiki/Pando_(tree)) (*Populus tremuloides*), the world's largest organism — a single aspen clone where individual trunks (ramets) share one root system (genet).
+
+---
+
+## The Problem
+
+AI coding assistants (Claude Code, Cursor, Codex) waste enormous tokens re-reading your codebase every session:
+
+| Without ramets | With ramets | Savings |
+|---|---|---|
+| Read knowledge graph: **212K tokens** | Session summary injection: ~400 tokens | **99.8%** |
+| Re-read files on branch switch: ~50K | Delta summary: ~200 tokens | **99.6%** |
+| "What did we decide?" — grep history: ~10K | `ramets decisions`: ~300 tokens | **97%** |
+| New session, re-explore codebase: ~30K | SessionStart hook: ~500 tokens | **98%** |
+
+LLM providers aren't incentivized to fix this — more tokens means more subscription revenue. So we fix it ourselves.
+
+## Quick Start
+
+```bash
+pip install ramets
+
+cd your-repo
+ramets init          # Build genet, install hooks (~5 seconds)
+ramets query "how does authentication work?"   # ~300 tokens
+ramets status        # Show genet freshness, branch deltas
+ramets summary       # Session context (~400 tokens)
+ramets obsidian      # Generate Obsidian vault for visualization
+```
+
+## How It Works
+
+```
+Genet (shared root)    ──>  base knowledge graph from common ancestor
+  ├── Ramet: main      ──>  0 deltas (is the base)
+  ├── Ramet: feat/auth  ──>  12 deltas (added auth module)
+  ├── Ramet: fix/typo   ──>  2 deltas (renamed function)
+  └── Ramet: feat/api   ──>  28 deltas (new API layer)
+
+Total storage: ~100KB for 400 nodes (ramets codebase itself)
+```
+
+1. **`ramets init`** builds the genet from tree-sitter AST extraction (via [graphify](https://pypi.org/project/graphifyy/))
+2. **Git hooks** fire on every commit/checkout — zero LLM tokens, all local computation
+3. **Claude Code hooks** inject pre-computed summaries at session start (~400 tokens)
+4. **`ramets query`** does keyword + BFS traversal with configurable token budgets
+
+**Git hooks do ALL computation. The LLM only consumes pre-computed results.**
+
+## Features
+
+### Delta-Encoded Knowledge Graphs
+- **Genet**: shared base graph (zlib-compressed, ~80KB)
+- **Ramets**: per-branch deltas — only what changed (add/remove/modify nodes and edges)
+- Concurrent worktree access via SQLite WAL mode
+- Storage: **104KB** for 408 nodes, 837 edges (real measurement on ramets codebase)
+
+### Git Hooks (Zero Token Cost)
+
+| Hook | Trigger | What it does |
+|---|---|---|
+| post-commit | Every commit | Compute branch delta (AST diff vs genet) |
+| post-checkout | Branch switch | Register branch, prep snapshot |
+| post-merge | After pull/merge | Recompute deltas |
+| post-rewrite | After rebase | Rebuild deltas for rewritten commits |
+
+### Claude Code Hooks (Token Savings)
+
+| Hook | Trigger | Tokens saved |
+|---|---|---|
+| SessionStart | Session begins | ~212K (injects 400-token summary instead) |
+| UserPromptSubmit | User sends prompt | ~30-50K (redirects to graph query) |
+| PreToolUse | File read attempted | ~10-50K (gates expensive reads) |
+
+### Decision Tracking
+
+Structured records of "AI suggested X, user chose Y" — not natural language summaries.
+
+```bash
+ramets decide \
+  -q "Which auth strategy?" \
+  -o "JWT:Stateless tokens" \
+  -o "Session cookies:Server-side sessions" \
+  -c 0 \
+  -r "Stateless fits our microservices design" \
+  --category architecture \
+  --confidence 0.85
+
+ramets decisions                        # List active decisions
+ramets decisions -s "auth"              # Full-text search
+ramets decisions --id abc123            # View decision detail
+```
+
+### Obsidian Visualization
+
+```bash
+ramets obsidian                         # Generate vault
+ramets obsidian --open                  # Generate and open in Obsidian
+ramets obsidian --all-branches          # Include all branch layers
+```
+
+Generates a navigable vault with:
+- **Base layer**: Community-colored nodes with `[[wikilinks]]`
+- **Branch delta layers**: Added/modified/removed nodes per branch
+- **Decision notes**: Structured choices with options and rationale
+- **Graph settings**: Community coloring for the graph view
+
+### MCP Server (15 tools)
+
+```bash
+pip install ramets[mcp]
+ramets serve                            # stdio transport
+# Or: claude mcp add ramets -- ramets serve
+```
+
+Tools: `query_graph`, `get_node`, `diff_branches`, `session_summary`, `record_decision`, `list_decisions`, `search_decisions`, `generate_obsidian_vault`, and more.
+
+## Architecture
+
+```
+.ramets/store.db (SQLite, WAL mode)
+├── genet         — shared root graph (compressed blob)
+├── ramets        — materialized per-branch snapshots
+├── ramet_deltas  — delta log per branch
+├── decisions     — structured decision records
+├── decision_edges — decision relationship graph
+├── sessions      — AI session tracking
+└── branches      — branch registry
+```
+
+## CLI Reference
+
+```
+ramets init              Create .ramets/, build genet, install hooks
+ramets build             Full genet rebuild from HEAD
+ramets update            Compute branch delta vs genet (called by hooks)
+ramets status            Genet freshness, ramet count, storage
+ramets query "..."       BFS traversal on current branch graph
+ramets diff feat/a main  Graph diff between branches
+ramets summary           Compact summary for session injection (~400 tokens)
+ramets decide            Record a structured decision
+ramets decisions         List/search decisions for current branch
+ramets obsidian          Generate Obsidian vault with branch layers
+ramets obsidian --open   Generate and open in Obsidian
+ramets serve             Start MCP server (stdio)
+ramets gc                Prune dead ramets, compact DB
+```
+
+## Development
+
+```bash
+git clone https://github.com/panne027/ramets.git
+cd ramets
+pip install -e ".[dev]"
+pytest tests/ -v                         # 70 tests
+ruff check src/ tests/                   # Lint
+ruff format src/ tests/                  # Format
+```
+
+## Requirements
+
+- Python >= 3.10
+- Git repository
+- [graphify](https://pypi.org/project/graphifyy/) (installed as dependency)
+
+## License
+
+MIT

ramets-0.3.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ramets"
+version = "0.3.0"
+description = "Per-branch AI coding context — delta-encoded knowledge graphs, decision tracking, and Obsidian visualization. Your codebase is one organism. Each branch is a ramet."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Harish Panneer Selvam"},
+]
+keywords = [
+    "ai", "coding", "context", "git", "worktree", "knowledge-graph",
+    "obsidian", "claude", "cursor", "codex", "branch", "delta",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "networkx>=3.0",
+    "click>=8.0",
+    "pydantic>=2.0",
+    "graphifyy>=0.3.10",
+    "jinja2>=3.0",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0", "fastmcp>=0.1"]
+all = ["mcp>=1.0", "fastmcp>=0.1"]
+dev = ["pytest>=7.0", "pytest-asyncio", "ruff", "mypy"]
+
+[project.scripts]
+ramets = "ramets.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/panne027/ramets"
+Repository = "https://github.com/panne027/ramets"
+Issues = "https://github.com/panne027/ramets/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# ── Semantic Release ──────────────────────────────────────────
+# Reads conventional commits (feat:, fix:, etc.) to determine version bumps.
+# feat: → minor bump, fix: → patch bump, BREAKING CHANGE → major bump.
+# Only releases from main branch.
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/ramets/__init__.py:__version__"]
+branch = "main"
+commit_message = "chore(release): {version}\n\nAutomatically generated by python-semantic-release"
+upload_to_pypi = false  # Handled by gh-action-pypi-publish via OIDC
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "perf", "refactor", "docs", "test", "chore"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf", "refactor"]
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"

ramets-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ramets-0.3.0/src/ramets/__init__.py

@@ -0,0 +1,13 @@
+"""ramets — Per-branch AI coding context.
+
+Your codebase is one organism. Each branch is a ramet.
+
+Named after Pando (Populus tremuloides), the world's largest organism —
+a single aspen clone where individual trunks (ramets) share one root system (genet).
+
+- Genet: the shared base knowledge graph (common ancestor of all branches)
+- Ramets: per-branch delta-encoded graphs (individual trunks from the shared root)
+- Decisions: structured tracking of AI suggestions and user choices
+"""
+
+__version__ = "0.3.0"

ramets-0.3.0/src/ramets/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m ramets`."""
+
+from ramets.cli import main
+
+main()