memgit 0.1.5__tar.gz → 0.3.0__tar.gz

{memgit-0.1.5 → memgit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.1.5
+Version: 0.3.0
 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
@@ -27,6 +27,9 @@ 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"
+Provides-Extra: cloud
+Requires-Dist: pynacl>=1.5; extra == "cloud"
+Requires-Dist: httpx>=0.27; extra == "cloud"
 Dynamic: license-file
 
 <p align="center">
@@ -52,6 +55,8 @@ You've probably already tried both. Here's why they hit a ceiling:
 | Capability | claude.md | mem-search plugin | **memgit** |
 |---|---|---|---|
 | Loads only relevant context | ❌ loads everything | ⚠️ loads recent observations | ✅ BM25 search — top-k per query |
+| Project-aware across a multi-repo life | ❌ per-file | ❌ | ✅ memories carry a `project`; the current workspace ranks first |
+| Adopt on an existing codebase | ❌ starts blank | ❌ starts blank | ✅ `memgit onboard` — seed the store from the repo in one pass |
 | Version history | ❌ | ❌ | ✅ full commit log |
 | Diff between sessions | ❌ | ❌ | ✅ `memgit diff` |
 | Roll back a wrong memory | ❌ manual edit | ❌ | ✅ `memgit rollback` |
@@ -166,49 +171,107 @@ pip install memgit
 ```bash
 # 1. Install and initialize
 pip install memgit
-memgit init               # auto-detects best location (~/.claude/memgit-store etc.)
+memgit init               # auto-detects the best location, finds your existing
+                          # Claude Code memories, and offers to import them
 
-# 2. Import existing memories (if you use Claude Code)
-memgit import claude-code ~/.claude/projects/
-
-# 3. Register with your AI tools (interactive picker)
+# 2. Register with your AI tools (interactive picker)
 memgit setup
 
-# 4. See your token savings
+# 3. See your token savings
 memgit stats
 ```
 
+`init` walks you through it — no paths to hunt down. (Importing later is one command with no arguments: `memgit sync` auto-finds `~/.claude/projects/*/memory`.)
+
 Restart your AI tool — it now searches your memory store at the start of every session.
 
 ---
 
+## Adopting memgit mid-project
+
+Memory tools have a cold-start problem: install one halfway through a project and it knows *nothing* — there's no initial point, and context only trickles in from future sessions. memgit solves this with a one-time seeding pass:
+
+```bash
+cd your-project
+memgit onboard          # prints the bootstrap brief
+```
+
+The brief tells your AI agent exactly what to do: read the README/docs/manifests and recent git history, extract 10–20 durable facts (purpose, architecture, conventions, current state, gotchas), save each as a typed memory, and checkpoint the seed set. Paste it into a session — or don't: if the AI searches memory in a project that has none, the MCP server itself replies with the bootstrap instructions instead of a bare "no results."
+
+Memories are **project-scoped**: each carries the workspace it belongs to, searches boost the project you're standing in (global rules still surface), and the resume digest leads with *your current project's* recent work — not whatever repo you touched last night.
+
+---
+
+## Resume where you left off
+
+Ask an AI "can we proceed on the pending tasks?" in a fresh session and it will guess from whatever file happens to be open. `memgit resume` replaces the guess with the record:
+
+```bash
+memgit resume            # last checkpoints, work in flight, recent + critical memories
+memgit resume --plain    # plain text, for piping into an AI context
+memgit resume --json     # for tooling
+```
+
+Wire it into Claude Code so every new session **starts** with this digest in context — no tool call, no judgment required:
+
+```bash
+memgit setup hooks       # installs a SessionStart hook (~/.claude/settings.json)
+```
+
+The digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
+
+---
+
 ## Scale to 10,000+ sessions
 
-After months of use, your checkpoint history grows. `memgit squash` handles it:
+After months of use, your checkpoint history grows. Squash compresses it, gc reclaims the disk:
 
 ```bash
 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
+
+memgit gc                        # delete unreachable objects, trim reflogs
+memgit gc --dry-run              # preview
+memgit gc --squash-keep 200      # compact history, then sweep
+```
+
+The current memory **state is always preserved** — and squash is lossless-in-substance: every collapsed checkpoint leaves a one-line record (time, author, diff, message) in an append-only archive under `.memgit/logs/archive/` that gc never touches. Benchmark on a 2,000-checkpoint store: **94% smaller** (39.5 MB → 2.2 MB), `fsck` clean. History operations stay O(1) as the chain grows (SHA resolution and checkpoint counting measured at ~0.08 ms at 2,000 checkpoints).
+
+---
+
+## Multiple agents, one memory
+
+All writes go through a git-style store lock (0.08 ms overhead), so concurrent agents can't corrupt the store or lose each other's updates. Two patterns:
+
+**Shared thread** — agents write concurrently; if one commits while another has work staged, the second commit auto-merges (three-way, against the recorded base) instead of clobbering. Set `MEMGIT_AUTHOR=agent-name` so each checkpoint says who did it.
+
+**Thread per agent** — isolate, then integrate:
+
+```bash
+memgit thread create agent-1     # branch off for each agent
+# ... agents work on their own threads ...
+memgit merge agent-1             # three-way merge back (common-ancestor based)
 ```
 
-The current memory **state is always preserved** — squash only compresses the historical chain.
+Conflicts (same memory changed on both sides) resolve to the newest version; an edit always beats a delete. Both histories are preserved.
 
 ---
 
 ## What the AI sees
 
-Once registered via MCP, every AI tool gets 5 tools:
+Once registered via MCP, every AI tool gets 6 tools:
 
 | Tool | When the AI uses it |
 |---|---|
-| `search_memories` | Start of every session — loads relevant context automatically |
+| `resume_session` | When the request depends on prior state — "continue", "the pending tasks", session start |
+| `search_memories` | Before answering anything that touches past work or preferences |
 | `get_memory` | When it needs full details of a specific memory |
 | `list_memories` | To browse or audit what's stored |
 | `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 — making it default behavior, not opt-in.
+The tool descriptions teach the AI **judgment** — "does this request depend on state you don't have in context?" — rather than keyword triggers. Measured cost of the whole tool surface: ~1,150 tokens once per session; a `resume_session` reply is ~335.
 
 ---
 
@@ -217,7 +280,8 @@ The tool descriptions tell the AI **when** to call each one — making it defaul
 ```bash
 # Core (git-like)
 memgit init                       # initialize store (auto-detects best path)
-memgit add <slug> <rule>          # stage a memory
+memgit onboard                    # bootstrap brief for an existing codebase
+memgit add <slug> <rule>          # stage a memory (--body for full detail, --project to scope)
 memgit commit -m "message"        # checkpoint current state
 memgit log                        # history
 memgit diff [sha1] [sha2]         # what changed
@@ -226,16 +290,19 @@ 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
+memgit resume                     # where we left off — session-start digest
+memgit merge <thread>             # three-way merge a thread into the current one
 
 # Scale & proof
-memgit stats                      # token savings vs alternatives
+memgit squash                     # compress old history (archives what it collapses)
+memgit gc                         # reclaim disk: sweep unreachable objects
+memgit stats                      # token savings + disk usage
 memgit lint                       # validate all memories
 memgit fsck                       # verify store integrity
 
 # Import / export
-memgit sync                       # sync from Claude Code files + commit
-memgit import claude-code <path>
+memgit sync                       # sync from Claude Code files + commit (auto-finds them)
+memgit import claude-code [path]  # path optional — defaults to ~/.claude/projects/*/memory
 memgit import file <path>
 memgit export <slug>
 
@@ -254,6 +321,8 @@ memgit setup cursor
 memgit setup windsurf
 memgit setup cline
 memgit setup continue
+memgit setup gemini-cli
+memgit setup hooks                # Claude Code SessionStart hook → auto-inject resume digest
 
 # Server
 memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)
@@ -298,9 +367,11 @@ The same memory in TOON:
 ```
 TOON1|fb|no-db-mock|2026-07-01T10:00Z
 #testing #database
+PROJ:my-app
 RULE:Never mock the database in tests
 WHY:Mocked tests passed but prod migration failed last quarter
 WHEN:Any persistence test
+BODY:Full long-form detail lives here, losslessly (newlines escaped).\nSearch returns the compact RULE; get_memory returns everything.
 ```
 
 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.
@@ -353,10 +424,15 @@ 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] `memgit resume` + SessionStart hook — sessions start with "where we left off"
+- [x] `memgit gc` — space reclamation (mark-and-sweep, lossless squash archive)
+- [x] Multi-agent write safety — store lock, auto-merge commits, `memgit merge`
 - [x] PyPI + Homebrew (tap) + npm published (v0.1.5)
 - [ ] 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] Lossless memories — full `body` alongside the compact rule (v0.3.0)
+- [x] Project-scoped memories + `memgit onboard` mid-project bootstrap (v0.3.0)
 - [x] VS Code extension (v0.1.5, Marketplace: code416-memgit.memgit)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings (Phase 4)

{memgit-0.1.5 → memgit-0.3.0}/README.md

@@ -21,6 +21,8 @@ You've probably already tried both. Here's why they hit a ceiling:
 | Capability | claude.md | mem-search plugin | **memgit** |
 |---|---|---|---|
 | Loads only relevant context | ❌ loads everything | ⚠️ loads recent observations | ✅ BM25 search — top-k per query |
+| Project-aware across a multi-repo life | ❌ per-file | ❌ | ✅ memories carry a `project`; the current workspace ranks first |
+| Adopt on an existing codebase | ❌ starts blank | ❌ starts blank | ✅ `memgit onboard` — seed the store from the repo in one pass |
 | Version history | ❌ | ❌ | ✅ full commit log |
 | Diff between sessions | ❌ | ❌ | ✅ `memgit diff` |
 | Roll back a wrong memory | ❌ manual edit | ❌ | ✅ `memgit rollback` |
@@ -135,49 +137,107 @@ pip install memgit
 ```bash
 # 1. Install and initialize
 pip install memgit
-memgit init               # auto-detects best location (~/.claude/memgit-store etc.)
+memgit init               # auto-detects the best location, finds your existing
+                          # Claude Code memories, and offers to import them
 
-# 2. Import existing memories (if you use Claude Code)
-memgit import claude-code ~/.claude/projects/
-
-# 3. Register with your AI tools (interactive picker)
+# 2. Register with your AI tools (interactive picker)
 memgit setup
 
-# 4. See your token savings
+# 3. See your token savings
 memgit stats
 ```
 
+`init` walks you through it — no paths to hunt down. (Importing later is one command with no arguments: `memgit sync` auto-finds `~/.claude/projects/*/memory`.)
+
 Restart your AI tool — it now searches your memory store at the start of every session.
 
 ---
 
+## Adopting memgit mid-project
+
+Memory tools have a cold-start problem: install one halfway through a project and it knows *nothing* — there's no initial point, and context only trickles in from future sessions. memgit solves this with a one-time seeding pass:
+
+```bash
+cd your-project
+memgit onboard          # prints the bootstrap brief
+```
+
+The brief tells your AI agent exactly what to do: read the README/docs/manifests and recent git history, extract 10–20 durable facts (purpose, architecture, conventions, current state, gotchas), save each as a typed memory, and checkpoint the seed set. Paste it into a session — or don't: if the AI searches memory in a project that has none, the MCP server itself replies with the bootstrap instructions instead of a bare "no results."
+
+Memories are **project-scoped**: each carries the workspace it belongs to, searches boost the project you're standing in (global rules still surface), and the resume digest leads with *your current project's* recent work — not whatever repo you touched last night.
+
+---
+
+## Resume where you left off
+
+Ask an AI "can we proceed on the pending tasks?" in a fresh session and it will guess from whatever file happens to be open. `memgit resume` replaces the guess with the record:
+
+```bash
+memgit resume            # last checkpoints, work in flight, recent + critical memories
+memgit resume --plain    # plain text, for piping into an AI context
+memgit resume --json     # for tooling
+```
+
+Wire it into Claude Code so every new session **starts** with this digest in context — no tool call, no judgment required:
+
+```bash
+memgit setup hooks       # installs a SessionStart hook (~/.claude/settings.json)
+```
+
+The digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
+
+---
+
 ## Scale to 10,000+ sessions
 
-After months of use, your checkpoint history grows. `memgit squash` handles it:
+After months of use, your checkpoint history grows. Squash compresses it, gc reclaims the disk:
 
 ```bash
 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
+
+memgit gc                        # delete unreachable objects, trim reflogs
+memgit gc --dry-run              # preview
+memgit gc --squash-keep 200      # compact history, then sweep
+```
+
+The current memory **state is always preserved** — and squash is lossless-in-substance: every collapsed checkpoint leaves a one-line record (time, author, diff, message) in an append-only archive under `.memgit/logs/archive/` that gc never touches. Benchmark on a 2,000-checkpoint store: **94% smaller** (39.5 MB → 2.2 MB), `fsck` clean. History operations stay O(1) as the chain grows (SHA resolution and checkpoint counting measured at ~0.08 ms at 2,000 checkpoints).
+
+---
+
+## Multiple agents, one memory
+
+All writes go through a git-style store lock (0.08 ms overhead), so concurrent agents can't corrupt the store or lose each other's updates. Two patterns:
+
+**Shared thread** — agents write concurrently; if one commits while another has work staged, the second commit auto-merges (three-way, against the recorded base) instead of clobbering. Set `MEMGIT_AUTHOR=agent-name` so each checkpoint says who did it.
+
+**Thread per agent** — isolate, then integrate:
+
+```bash
+memgit thread create agent-1     # branch off for each agent
+# ... agents work on their own threads ...
+memgit merge agent-1             # three-way merge back (common-ancestor based)
 ```
 
-The current memory **state is always preserved** — squash only compresses the historical chain.
+Conflicts (same memory changed on both sides) resolve to the newest version; an edit always beats a delete. Both histories are preserved.
 
 ---
 
 ## What the AI sees
 
-Once registered via MCP, every AI tool gets 5 tools:
+Once registered via MCP, every AI tool gets 6 tools:
 
 | Tool | When the AI uses it |
 |---|---|
-| `search_memories` | Start of every session — loads relevant context automatically |
+| `resume_session` | When the request depends on prior state — "continue", "the pending tasks", session start |
+| `search_memories` | Before answering anything that touches past work or preferences |
 | `get_memory` | When it needs full details of a specific memory |
 | `list_memories` | To browse or audit what's stored |
 | `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 — making it default behavior, not opt-in.
+The tool descriptions teach the AI **judgment** — "does this request depend on state you don't have in context?" — rather than keyword triggers. Measured cost of the whole tool surface: ~1,150 tokens once per session; a `resume_session` reply is ~335.
 
 ---
 
@@ -186,7 +246,8 @@ The tool descriptions tell the AI **when** to call each one — making it defaul
 ```bash
 # Core (git-like)
 memgit init                       # initialize store (auto-detects best path)
-memgit add <slug> <rule>          # stage a memory
+memgit onboard                    # bootstrap brief for an existing codebase
+memgit add <slug> <rule>          # stage a memory (--body for full detail, --project to scope)
 memgit commit -m "message"        # checkpoint current state
 memgit log                        # history
 memgit diff [sha1] [sha2]         # what changed
@@ -195,16 +256,19 @@ 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
+memgit resume                     # where we left off — session-start digest
+memgit merge <thread>             # three-way merge a thread into the current one
 
 # Scale & proof
-memgit stats                      # token savings vs alternatives
+memgit squash                     # compress old history (archives what it collapses)
+memgit gc                         # reclaim disk: sweep unreachable objects
+memgit stats                      # token savings + disk usage
 memgit lint                       # validate all memories
 memgit fsck                       # verify store integrity
 
 # Import / export
-memgit sync                       # sync from Claude Code files + commit
-memgit import claude-code <path>
+memgit sync                       # sync from Claude Code files + commit (auto-finds them)
+memgit import claude-code [path]  # path optional — defaults to ~/.claude/projects/*/memory
 memgit import file <path>
 memgit export <slug>
 
@@ -223,6 +287,8 @@ memgit setup cursor
 memgit setup windsurf
 memgit setup cline
 memgit setup continue
+memgit setup gemini-cli
+memgit setup hooks                # Claude Code SessionStart hook → auto-inject resume digest
 
 # Server
 memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)
@@ -267,9 +333,11 @@ The same memory in TOON:
 ```
 TOON1|fb|no-db-mock|2026-07-01T10:00Z
 #testing #database
+PROJ:my-app
 RULE:Never mock the database in tests
 WHY:Mocked tests passed but prod migration failed last quarter
 WHEN:Any persistence test
+BODY:Full long-form detail lives here, losslessly (newlines escaped).\nSearch returns the compact RULE; get_memory returns everything.
 ```
 
 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.
@@ -322,10 +390,15 @@ 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] `memgit resume` + SessionStart hook — sessions start with "where we left off"
+- [x] `memgit gc` — space reclamation (mark-and-sweep, lossless squash archive)
+- [x] Multi-agent write safety — store lock, auto-merge commits, `memgit merge`
 - [x] PyPI + Homebrew (tap) + npm published (v0.1.5)
 - [ ] 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] Lossless memories — full `body` alongside the compact rule (v0.3.0)
+- [x] Project-scoped memories + `memgit onboard` mid-project bootstrap (v0.3.0)
 - [x] VS Code extension (v0.1.5, Marketplace: code416-memgit.memgit)
 - [ ] JetBrains plugin (Phase 3)
 - [ ] Semantic search via embeddings (Phase 4)

{memgit-0.1.5 → memgit-0.3.0}/memgit/__init__.py

@@ -1,3 +1,3 @@
 """memgit — git for AI memory."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"