memgit 0.1.1__tar.gz → 0.1.4__tar.gz

{memgit-0.1.1 → memgit-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.1.1
+Version: 0.1.4
 Summary: Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more
 License: MIT
 Project-URL: Homepage, https://memgit.dev
@@ -25,22 +25,23 @@ Requires-Dist: mcp>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-anyio>=0.0.0; extra == "dev"
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == "tokens"
 Dynamic: license-file
 
+<p align="center">
+  <img src="assets/logo.png" alt="memgit logo" width="120" />
+</p>
+
 # memgit — git for AI memory
 
-**Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs like code.**
+**Your AI assistants forget everything when the session ends. memgit fixes that.**
 
-```bash
-pip install memgit
-memgit init ~/.claude/memgit-store
-memgit setup all          # registers with every AI tool detected on your machine
-memgit stats              # see your token savings vs claude.md / other plugins
-```
+Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs like code. Switch from Claude to Cursor to ChatGPT mid-project — your context is already there.
 
 [![PyPI](https://img.shields.io/pypi/v/memgit)](https://pypi.org/project/memgit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-48%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-54%20passing-brightgreen)](tests/)
 
 ---
 
@@ -53,7 +54,7 @@ You've probably already tried both. Here's why they hit a ceiling:
 | Loads only relevant context | ❌ loads everything | ⚠️ loads recent observations | ✅ BM25 search — top-k per query |
 | Version history | ❌ | ❌ | ✅ full commit log |
 | Diff between sessions | ❌ | ❌ | ✅ `memgit diff` |
-| Roll back a wrong memory | ❌ manual edit | ❌ | ✅ `memgit checkout` |
+| Roll back a wrong memory | ❌ manual edit | ❌ | ✅ `memgit rollback` |
 | Works in Cursor, Windsurf, GPT | ❌ Claude only | ❌ Claude only | ✅ all via MCP / HTTP |
 | Team sync | ❌ copy-paste files | ❌ | ✅ `memgit git push` |
 | Scales to 10k+ sessions | ❌ file grows | ❌ search slows | ✅ `memgit squash` |
@@ -76,17 +77,16 @@ $ memgit stats
   ┌─────────────────────────────────────┬──────────────────┬───────────────────┬─────────────────────┐
   │ Approach                            │ Tokens/session   │ vs full load      │ $/session (GPT-4o)  │
   ├─────────────────────────────────────┼──────────────────┼───────────────────┼─────────────────────┤
-  │ claude.md / dump all memories       │ 12,840           │ 100%  baseline    │ $0.0642             │
-  │ mem-search plugin (top-20 obs)      │ 6,100 (est.)     │ ~47%              │ $0.0305             │
-  │ memgit search (BM25 top-8)          │ 640              │ 5%  (95% savings) │ $0.0032             │
+  │ claude.md / dump all memories       │ 12,840           │ 100%  baseline    │ $0.0321             │
+  │ memgit search (BM25 top-8)          │ 640              │ 5%  (95% savings) │ $0.0016             │
   └─────────────────────────────────────┴──────────────────┴───────────────────┴─────────────────────┘
 
   Weekly savings (10 sessions/week):
-    Tokens saved:   121,600/week
-    Cost saved:     $0.61/week  →  $31.70/year  (at GPT-4o input pricing)
+    Tokens saved:   122,000/week
+    Cost saved:     $0.31/week  →  $15.86/year  (at GPT-4o input pricing, $2.50/M)
 ```
 
-**Why such a big difference?** claude.md loads *all* context every session. mem-search loads recent observations. memgit uses BM25 relevance scoring — it loads *only the 8 memories most relevant to the current session*, not everything you've ever recorded.
+**Why such a big difference?** claude.md loads *all* context every session. memgit uses BM25 relevance scoring — it loads *only the 8 memories most relevant to the current session*, not everything you've ever recorded.
 
 ---
 
@@ -106,48 +106,31 @@ memgit's data model maps exactly to git:
 | `memgit squash --keep-last 100` | `git rebase -i --autosquash` |
 | `memgit git push` | `git push` |
 
-And this is not metaphorical — memgit uses a **content-addressed object store** (SHA-256 blobs) identical to git's architecture. Every memory has a stable SHA. Identical content has identical SHAs. The object store is tamper-evident.
+This is not metaphorical — memgit uses a **content-addressed object store** (SHA-256 blobs) identical to git's architecture. Every memory has a stable SHA. Identical content has identical SHAs. Old state is always recoverable.
 
 ---
 
 ## The store IS a git repo
 
-Every memory is a readable `.toon` file under `memories/`. You can push your entire memory set to GitHub with standard git:
-
-```bash
-cd ~/.claude/memgit-store
-git init
-git remote add origin git@github.com:yourteam/ai-memory.git
-git add memories/ .memgit/refs/
-git commit -m "session memories"
-git push
-```
-
-Or use the built-in command:
+Every memory is a readable `.toon` file under `memories/`. Push your entire memory set to GitHub with standard git:
 
 ```bash
 memgit git init --remote git@github.com:yourteam/ai-memory.git
 memgit git push
 ```
 
-Teammates pull and get your AI's learned rules, preferences, and lessons instantly:
+Teammates pull and start with your AI's learned rules from session 1:
 
 ```bash
 git clone git@github.com:yourteam/ai-memory.git ~/.claude/memgit-store
 memgit setup all
-# Their AI now knows everything your AI knows — from session 1
 ```
 
 You can `grep`, `git blame`, and `git diff` your memories just like code:
 
 ```bash
-# Search across all memories
 grep -rl "database" ~/.claude/memgit-store/memories/
-
-# See who changed what
 git log --follow memories/no-db-mock.toon
-
-# What changed this week?
 git diff HEAD~7 memories/
 ```
 
@@ -155,19 +138,25 @@ git diff HEAD~7 memories/
 
 ## Install
 
+**Mac / Linux:**
 ```bash
 pip install memgit
 ```
 
-Homebrew (after tap published):
+**Mac (Homebrew):**
 ```bash
 brew tap code4161/tap && brew install memgit
 ```
 
-npm (for Node-based tools — no Python needed):
-```bash
-# In any AI tool's MCP config:
-{ "command": "npx", "args": ["-y", "memgit-mcp"] }
+**Windows:**
+```powershell
+pip install memgit
+```
+(`choco install memgit` is not live yet — the Chocolatey package is not on community.chocolatey.org. Use pip until it lands.)
+
+**Any AI tool config (no Python needed — npx auto-installs on first run):**
+```json
+{ "mcpServers": { "memgit": { "command": "npx", "args": ["-y", "memgit-mcp"] } } }
 ```
 
 ---
@@ -177,21 +166,16 @@ npm (for Node-based tools — no Python needed):
 ```bash
 # 1. Install and initialize
 pip install memgit
-memgit init ~/.claude/memgit-store
+memgit init               # auto-detects best location (~/.claude/memgit-store etc.)
 
 # 2. Import existing memories (if you use Claude Code)
-cd ~/.claude/memgit-store
 memgit import claude-code ~/.claude/projects/
 
-# 3. Register with every AI tool on your machine
-memgit setup all
+# 3. Register with your AI tools (interactive picker)
+memgit setup
 
 # 4. See your token savings
 memgit stats
-
-# 5. Push to share with teammates
-memgit git init --remote git@github.com:yourteam/ai-memory.git
-memgit git push
 ```
 
 Restart your AI tool — it now searches your memory store at the start of every session.
@@ -200,25 +184,15 @@ Restart your AI tool — it now searches your memory store at the start of every
 
 ## Scale to 10,000+ sessions
 
-After months of use, your checkpoint history grows. `memgit squash` handles it — like `git rebase --autosquash` but automatic:
+After months of use, your checkpoint history grows. `memgit squash` handles it:
 
 ```bash
-# Keep last 100 checkpoints; squash everything older into one baseline
-memgit squash --keep-last 100
-
-# Squash everything older than 30 days
-memgit squash --older-than 30
-
-# Preview first
-memgit squash --keep-last 100 --dry-run
-# → would squash 847 checkpoints (baseline: 2026-04-01) → keep 100 recent ones
-
-# After squash: history is compact, current memories are fully preserved
-memgit log --oneline  # clean, readable history
-memgit list           # all memories still there
+memgit squash --keep-last 100    # keep last 100 checkpoints, squash everything older
+memgit squash --older-than 30    # squash everything older than 30 days
+memgit squash --dry-run          # preview first
 ```
 
-The current memory **state is always preserved** — squash only compresses the historical chain. At 10 sessions/day, squash once a month to keep history manageable.
+The current memory **state is always preserved** — squash only compresses the historical chain.
 
 ---
 
@@ -234,7 +208,7 @@ Once registered via MCP, every AI tool gets 5 tools:
 | `save_memory` | When it learns something worth keeping for next time |
 | `get_checkpoint_log` | To check when memories were last synced |
 
-The tool descriptions tell the AI **when** to call each one — including "call `search_memories` at the start of every session." This is what makes it default behavior, not opt-in.
+The tool descriptions tell the AI **when** to call each one — making it default behavior, not opt-in.
 
 ---
 
@@ -242,50 +216,51 @@ The tool descriptions tell the AI **when** to call each one — including "call
 
 ```bash
 # Core (git-like)
-memgit init <dir>             # initialize store
-memgit add <slug> <rule>      # stage a memory
-memgit commit -m "message"    # checkpoint current state
-memgit log                    # history
-memgit diff [sha1] [sha2]     # what changed
-memgit show <slug>            # display a memory
-memgit remove <slug>          # remove from active index (history preserved)
-memgit status                 # staged changes
-memgit search <query>         # BM25 relevance search
-memgit squash                 # compress old history
+memgit init                       # initialize store (auto-detects best path)
+memgit add <slug> <rule>          # stage a memory
+memgit commit -m "message"        # checkpoint current state
+memgit log                        # history
+memgit diff [sha1] [sha2]         # what changed
+memgit show <slug>                # display a memory
+memgit remove <slug>              # remove from active index (history preserved)
+memgit status                     # staged changes
+memgit search <query>             # BM25 relevance search
+memgit rollback <ref>             # restore state to a checkpoint (HEAD~N or SHA)
+memgit squash                     # compress old history
 
 # Scale & proof
-memgit stats                  # token savings vs alternatives
-memgit lint                   # validate all memories
-memgit fsck                   # verify store integrity
+memgit stats                      # token savings vs alternatives
+memgit lint                       # validate all memories
+memgit fsck                       # verify store integrity
 
 # Import / export
-memgit sync                   # sync from Claude Code files + commit
+memgit sync                       # sync from Claude Code files + commit
 memgit import claude-code <path>
 memgit import file <path>
 memgit export <slug>
 
 # Git sync (team features)
-memgit git init [--remote URL]   # initialize git in the store
+memgit git init [--remote URL]
 memgit git push [remote] [branch]
 memgit git pull [remote] [branch]
-memgit git export                # write flat memories/ files
-memgit git status                # changes since last git commit
+memgit git export
+memgit git status
 
 # AI tool registration
-memgit setup all
+memgit setup                      # interactive step-by-step picker
+memgit setup all                  # auto-register every detected tool
 memgit setup claude-code
 memgit setup cursor
 memgit setup windsurf
 memgit setup cline
 memgit setup continue
-memgit setup print-config <tool>
 
 # Server
-memgit serve                  # MCP stdio (Claude Code, Cursor, Windsurf, Cline)
-memgit serve --http           # HTTP REST (ChatGPT Custom Actions, Gemini)
+memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)
+memgit serve --http               # HTTP REST (ChatGPT Custom Actions, Gemini)
 
 # Visualization
-memgit graph                  # D3.js interactive relationship map
+memgit graph                      # D3.js interactive relationship map
 memgit thread list / switch / create
 ```
 
@@ -307,33 +282,9 @@ memgit thread list / switch / create
 
 ---
 
-## Default in every session — no manual steps
-
-`memgit setup claude-code` installs a Stop hook that auto-syncs memories when you end a session:
-
-```json
-// ~/.claude/settings.json (added automatically)
-{
-  "hooks": {
-    "Stop": [{
-      "hooks": [{
-        "type": "command",
-        "command": "cd ~/.claude/memgit-store && memgit sync 2>/dev/null || true",
-        "async": true
-      }]
-    }]
-  }
-}
-```
-
-And the MCP server's `search_memories` description tells every AI: *"call this at the start of every session."* This is enforced in the tool schema — the AI sees it as a required step, not an option.
-
----
-
-## TOON format — why it's 40–55% more token-efficient
-
-Standard markdown memory file (what claude.md uses):
+## TOON format — compact, readable, diffable
 
+Standard markdown memory file:
 ```markdown
 ## Rule: Never mock the database in tests
 **Type:** feedback  
@@ -342,10 +293,8 @@ Standard markdown memory file (what claude.md uses):
 **When to apply:** Any time writing tests that touch persistence layers.  
 **Tags:** testing, database
 ```
-*Token count: ~62*
 
 The same memory in TOON:
-
 ```
 TOON1|fb|no-db-mock|2026-07-01T10:00Z
 #testing #database
@@ -353,42 +302,12 @@ RULE:Never mock the database in tests
 WHY:Mocked tests passed but prod migration failed last quarter
 WHEN:Any persistence test
 ```
-*Token count: ~35*  **→ 44% fewer tokens for identical content**
-
-At 108 memories: **12,840 tokens (markdown) → 7,100 tokens (TOON) → 640 tokens (memgit search top-8)**
-
----
-
-## The business case — agent memory is the next asset class
 
-Source code is version-controlled because it's a company's primary asset. In 2026, **agent memory is equally valuable**:
+Measured with a real tokenizer, TOON is ~5–10% leaner than equivalent markdown — a nice bonus, not the headline. **The headline saving is retrieval**: memgit loads the top-8 relevant memories per query instead of everything.
 
-- Every AI session produces learned rules, discovered preferences, fixed mistakes
-- Today: these vanish when the session ends, or accumulate in unversioned markdown files
-- Tomorrow: teams will track, audit, merge, and ship their AI context as carefully as they ship code
+At 108 memories: **12,840 tokens (dump everything) → 640 tokens (memgit BM25 top-8)**
 
-memgit is the git layer for that transition. Built for the moment when "what did the AI know when it made that decision?" becomes as important as "who wrote that line of code?"
-
----
-
-## Team workflow
-
-```
-# Day 1: Set up shared memory
-memgit git init --remote git@github.com:acme/ai-memory.git
-memgit git push
-
-# Every session: memories auto-sync via Stop hook
-[session ends] → memgit sync → new checkpoint created
-
-# Weekly: push to share with team
-memgit git push
-
-# New teammate joins:
-git clone git@github.com:acme/ai-memory.git ~/.claude/memgit-store
-memgit setup all
-# Their AI starts with 6 months of team-learned context — Day 1
-```
+For exact token counts in `memgit stats`, install the optional tokenizer: `pip install "memgit[tokens]"`.
 
 ---
 
@@ -399,19 +318,13 @@ memgit setup all
   .memgit/
     objects/     ← SHA-256 content-addressed blobs (gzip compressed)
     refs/threads/main   ← HEAD checkpoint SHA
-    TOON_INDEX   ← active slug→sha mapping (cache, recoverable via fsck)
+    TOON_INDEX   ← active slug→sha mapping
     config       ← author, default thread
     logs/        ← ref change audit trail
   memories/      ← flat .toon files (git-trackable, human-readable)
-    no-db-mock.toon
-    trading-rules.toon
-    ...
   .git/          ← standard git repo (after `memgit git init`)
-  .gitignore     ← excludes .memgit/objects/ (binary blobs)
 ```
 
-The object store is **content-addressed**: same memory content = same SHA = stored once. Modifying a memory creates a new object and a new checkpoint pointing to it. Old state is always recoverable.
-
 ---
 
 ## Contributing
@@ -431,7 +344,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## Roadmap
 
 - [x] Content-addressed object store (git-identical architecture)
-- [x] TOON format (40–55% token reduction vs markdown)
+- [x] TOON format (compact line-oriented memory format)
 - [x] MCP server — Claude Code, Cursor, Windsurf, Cline, Continue.dev
 - [x] HTTP server — ChatGPT Custom Actions, Gemini function calling
 - [x] BM25 relevance search (load only what matters)
@@ -440,12 +353,14 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 - [x] `memgit git push/pull` — team sync via standard git
 - [x] Flat `memories/` directory — grep/diff/blame your memories
 - [x] D3.js graph visualization of memory relationships
-- [x] Multi-platform distribution (PyPI, Homebrew, npm, Chocolatey, winget)
-- [ ] PyPI publish (v0.1.0)
-- [ ] VS Code extension (Phase 3)
+- [x] PyPI + Homebrew (tap) + npm published (v0.1.4)
+- [ ] Chocolatey (not yet live on community.chocolatey.org)
+- [x] Interactive setup wizard (`memgit setup`)
+- [x] Smart `memgit init` (auto-detects tool, no path needed)
+- [x] VS Code extension (v0.1.4, Marketplace: code416-memgit.memgit)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings (Phase 4)
-- [ ] memgit.dev website (Phase 4)
+- [x] memgit.dev website (live)
 - [ ] Memory compression / auto-summarization (Phase 5)
 - [ ] Team access control + audit trail (Phase 5)
 - [ ] Memory marketplace — share reusable context packs (Phase 6)