memgit 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -193,10 +193,10 @@ Memory tools have a cold-start problem: install one halfway through a project an
 
 ```bash
 cd your-project
-memgit onboard          # prints the bootstrap brief
+memgit onboard          # mines the repo, 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."
+`onboard` first extracts a **repo digest** deterministically — git history (recent commit subjects, hot files/directories by churn, authors, branch, tags), detected stack from manifests, and the docs worth reading — using bounded, read-only probes that stay near-instant even on huge repositories. The brief then tells your AI agent exactly what to do with it: read only the listed files (no tree crawling), 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.
 

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

@@ -159,10 +159,10 @@ Memory tools have a cold-start problem: install one halfway through a project an
 
 ```bash
 cd your-project
-memgit onboard          # prints the bootstrap brief
+memgit onboard          # mines the repo, 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."
+`onboard` first extracts a **repo digest** deterministically — git history (recent commit subjects, hot files/directories by churn, authors, branch, tags), detected stack from manifests, and the docs worth reading — using bounded, read-only probes that stay near-instant even on huge repositories. The brief then tells your AI agent exactly what to do with it: read only the listed files (no tree crawling), 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.
 

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

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

{memgit-0.3.0 → memgit-0.3.1}/memgit/cli.py

@@ -369,18 +369,12 @@ ONBOARD_BRIEF = """\
 This project has {count} memories in memgit{count_note}. A memory store that
 starts empty mid-project is useless until it is seeded — do that now, once,
 and every future session (in any AI tool) starts oriented.
-
+{digest_section}
 ## Instructions for the AI operator
 
 Extract 10–20 DURABLE facts about this project and save each one as a memory
 (via the memgit MCP `save_memory` tool, or `memgit add` in a shell).
-Read, in this order, whatever exists:
-
-1. README / CLAUDE.md / CONTRIBUTING / docs/ — purpose, architecture, setup
-2. Package manifests (package.json, pyproject.toml, go.mod, …) — stack, entry points, scripts
-3. `git log --oneline -30` and recent PRs — what is being worked on RIGHT NOW
-4. Config/env samples, CI files — deploy targets, environments, gates
-5. The code layout itself — modules, boundaries, naming conventions
+{reading_plan}
 
 ## What to save (one memory each, not a dump)
 
@@ -403,28 +397,71 @@ Checkpoint the seed set so it is versioned from day one:
 Then verify: `memgit search "<something about this project>"` should hit.
 """
 
+_READING_PLAN_WITH_DIGEST = """\
+The repo digest above was extracted deterministically from git and the
+filesystem — treat it as ground truth and do NOT re-derive it. On a large
+repo, do NOT crawl the tree. Work only from:
+
+1. The "Read these first" files listed in the digest — purpose, architecture, setup
+2. The manifests listed — stack, entry points, scripts, dependencies
+3. The recent commit subjects + hot areas — what is being worked on RIGHT NOW
+   (turn these into the "current state / active work" memory)
+4. Config/env samples and CI files if present — deploy targets, environments, gates"""
+
+_READING_PLAN_GENERIC = """\
+Read, in this order, whatever exists:
+
+1. README / CLAUDE.md / CONTRIBUTING / docs/ — purpose, architecture, setup
+2. Package manifests (package.json, pyproject.toml, go.mod, …) — stack, entry points, scripts
+3. `git log --oneline -30` and recent PRs — what is being worked on RIGHT NOW
+4. Config/env samples, CI files — deploy targets, environments, gates
+5. The code layout itself — modules, boundaries, naming conventions"""
+
 
 @cli.command()
 @click.option('--project', '-P', default=None,
               help='Project label (default: derived from the current directory)')
 @click.option('--path', 'proj_path', default='.', type=click.Path(exists=True),
               help='Project directory to onboard (default: cwd)')
-def onboard(project, proj_path):
+@click.option('--json', 'fmt_json', is_flag=True, help='Emit the raw repo digest as JSON')
+def onboard(project, proj_path, fmt_json):
     """Print the bootstrap brief for adopting memgit on an existing project.
 
     memgit only knows what has been saved — a project adopted midway starts
-    with zero context. This prints a step-by-step brief for an AI agent (or
-    you) to seed the store from the codebase: README, docs, git history,
-    conventions. Paste it into your AI session, or run
+    with zero context. This mines the repo's git history and filesystem
+    (bounded and read-only, fast even on huge repos) into a factual digest,
+    then prints a step-by-step brief for an AI agent (or you) to seed the
+    store from it. Paste it into your AI session, or run
     `memgit onboard | pbcopy`.
     """
+    from .gitdigest import build_digest, format_digest
     from .importer import project_label_from_path
 
     repo = _require_repo()
-    label = project or project_label_from_path(Path(proj_path)) or Path(proj_path).resolve().name
+    target = Path(proj_path)
+    label = project or project_label_from_path(target) or target.resolve().name
+
+    digest = build_digest(target)
+    if fmt_json:
+        import json as _j
+        digest['project'] = label
+        print(_j.dumps(digest, indent=2))
+        return
+
     count = sum(1 for m in repo.list() if m.project == label)
     count_note = '' if count else ' — it is a blank slate for this project'
-    print(ONBOARD_BRIEF.format(project=label, count=count, count_note=count_note))
+
+    rendered = format_digest(digest)
+    if rendered:
+        digest_section = ('\n## Repo digest (auto-extracted — trust it, don\'t re-derive)\n\n'
+                          f'{rendered}\n')
+        reading_plan = _READING_PLAN_WITH_DIGEST
+    else:
+        digest_section = ''
+        reading_plan = _READING_PLAN_GENERIC
+
+    print(ONBOARD_BRIEF.format(project=label, count=count, count_note=count_note,
+                               digest_section=digest_section, reading_plan=reading_plan))
 
 
 # ── log ───────────────────────────────────────────────────────────────────────

memgit-0.3.1/memgit/gitdigest.py

@@ -0,0 +1,158 @@
+"""Deterministic repo digest for onboarding — mine git + the filesystem
+so the AI operator starts from extracted facts, not exploration.
+
+Every probe is bounded (commit caps, timeouts, output clips) so this stays
+fast and safe on very large repositories, and every probe is read-only.
+A probe that fails or times out is simply omitted — never an error.
+"""
+
+from __future__ import annotations
+import subprocess
+from collections import Counter
+from pathlib import Path
+from typing import Optional
+
+# Bounds — chosen so the digest is near-instant even on monorepos.
+_GIT_TIMEOUT = 5          # seconds per git call
+_CHURN_COMMITS = 300      # commits sampled for hot-file analysis
+_RECENT_SUBJECTS = 15     # recent commit subjects shown
+_AUTHOR_SAMPLE = 500      # commits sampled for contributor list
+
+# Well-known files worth reading during onboarding, in reading order.
+_DOC_FILES = [
+    'CLAUDE.md', 'README.md', 'README.rst', 'CONTRIBUTING.md',
+    'ARCHITECTURE.md', 'AGENTS.md', 'CHANGELOG.md',
+]
+_MANIFEST_FILES = [
+    'package.json', 'pyproject.toml', 'setup.py', 'requirements.txt',
+    'go.mod', 'Cargo.toml', 'pom.xml', 'build.gradle', 'Gemfile',
+    'composer.json', 'mix.exs', 'Makefile', 'docker-compose.yml',
+    'Dockerfile',
+]
+
+_STACK_HINTS = {
+    'package.json': 'Node.js/TypeScript',
+    'pyproject.toml': 'Python',
+    'setup.py': 'Python',
+    'requirements.txt': 'Python',
+    'go.mod': 'Go',
+    'Cargo.toml': 'Rust',
+    'pom.xml': 'Java (Maven)',
+    'build.gradle': 'Java/Kotlin (Gradle)',
+    'Gemfile': 'Ruby',
+    'composer.json': 'PHP',
+    'mix.exs': 'Elixir',
+}
+
+
+def _git(args: list[str], cwd: Path) -> Optional[str]:
+    """Run one read-only git command; None on any failure or timeout."""
+    try:
+        out = subprocess.run(
+            ['git', '--no-pager'] + args,
+            cwd=str(cwd), capture_output=True, text=True, timeout=_GIT_TIMEOUT,
+        )
+        return out.stdout.strip() if out.returncode == 0 else None
+    except Exception:
+        return None
+
+
+def build_digest(path: Path) -> dict:
+    """Extract a bounded, factual digest of the repo at `path`.
+
+    Returns a dict; `has_git` False means only the filesystem probes ran.
+    """
+    path = path.resolve()
+    digest: dict = {'path': str(path), 'has_git': False}
+
+    # Filesystem probes (work with or without git)
+    docs = [f for f in _DOC_FILES if (path / f).is_file()]
+    manifests = [f for f in _MANIFEST_FILES if (path / f).is_file()]
+    stacks = sorted({_STACK_HINTS[m] for m in manifests if m in _STACK_HINTS})
+    digest['docs'] = docs
+    digest['manifests'] = manifests
+    digest['stacks'] = stacks
+    digest['has_docs_dir'] = (path / 'docs').is_dir()
+    digest['has_ci'] = (path / '.github' / 'workflows').is_dir() or (path / '.gitlab-ci.yml').is_file()
+
+    if _git(['rev-parse', '--is-inside-work-tree'], path) != 'true':
+        return digest
+    digest['has_git'] = True
+
+    digest['branch'] = _git(['branch', '--show-current'], path) or None
+    digest['last_commit_date'] = _git(['log', '-1', '--format=%as'], path)
+    count = _git(['rev-list', '--count', 'HEAD'], path)
+    digest['commit_count'] = int(count) if count and count.isdigit() else None
+    digest['latest_tag'] = _git(['describe', '--tags', '--abbrev=0'], path)
+
+    subjects = _git(['log', f'-{_RECENT_SUBJECTS}', '--no-merges', '--format=%s'], path)
+    digest['recent_subjects'] = (
+        [s.strip()[:100] for s in subjects.splitlines() if s.strip()] if subjects else []
+    )
+
+    authors = _git(['log', f'-{_AUTHOR_SAMPLE}', '--format=%an'], path)
+    if authors:
+        top = Counter(a.strip() for a in authors.splitlines() if a.strip())
+        digest['top_authors'] = [name for name, _ in top.most_common(5)]
+    else:
+        digest['top_authors'] = []
+
+    # Hot files/dirs: what actually changes is where the project lives.
+    churn = _git(
+        ['log', f'-{_CHURN_COMMITS}', '--no-merges', '--name-only', '--format='],
+        path,
+    )
+    if churn:
+        files = [f.strip() for f in churn.splitlines() if f.strip()]
+        file_counts = Counter(files)
+        dir_counts: Counter = Counter()
+        for f, n in file_counts.items():
+            top_level = f.split('/', 1)[0] if '/' in f else '(root)'
+            dir_counts[top_level] += n
+        digest['hot_files'] = [f for f, _ in file_counts.most_common(10)]
+        digest['hot_dirs'] = [d for d, _ in dir_counts.most_common(6)]
+    else:
+        digest['hot_files'] = []
+        digest['hot_dirs'] = []
+
+    return digest
+
+
+def format_digest(digest: dict) -> str:
+    """Render the digest as a markdown section for the onboarding brief."""
+    lines: list[str] = []
+    if digest.get('has_git'):
+        facts = []
+        if digest.get('commit_count'):
+            facts.append(f"{digest['commit_count']} commits")
+        if digest.get('branch'):
+            facts.append(f"branch `{digest['branch']}`")
+        if digest.get('last_commit_date'):
+            facts.append(f"last commit {digest['last_commit_date']}")
+        if digest.get('latest_tag'):
+            facts.append(f"latest tag {digest['latest_tag']}")
+        if facts:
+            lines.append(f"- Git: {' · '.join(facts)}")
+        if digest.get('top_authors'):
+            lines.append(f"- Recent authors: {', '.join(digest['top_authors'])}")
+    if digest.get('stacks'):
+        lines.append(f"- Stack: {', '.join(digest['stacks'])} "
+                     f"(manifests: {', '.join(digest['manifests'])})")
+    elif digest.get('manifests'):
+        lines.append(f"- Manifests: {', '.join(digest['manifests'])}")
+    read_first = list(digest.get('docs', []))
+    if digest.get('has_docs_dir'):
+        read_first.append('docs/')
+    if read_first:
+        lines.append(f"- Read these first: {', '.join(read_first)}")
+    if digest.get('hot_dirs'):
+        lines.append(f"- Hot areas (most-changed recently): {', '.join(digest['hot_dirs'])}")
+    if digest.get('hot_files'):
+        lines.append(f"- Most-changed files: {', '.join(digest['hot_files'][:6])}")
+    if digest.get('recent_subjects'):
+        lines.append('- Recent commit subjects (newest first):')
+        for s in digest['recent_subjects']:
+            lines.append(f'    · {s}')
+    if digest.get('has_ci'):
+        lines.append('- CI config present (.github/workflows or .gitlab-ci.yml)')
+    return '\n'.join(lines)

{memgit-0.3.0 → memgit-0.3.1}/memgit/mcp_server.py

@@ -403,7 +403,9 @@ def run_server(store_path: Path | None = None) -> None:
                         "docs and `git log --oneline -30`, extract 10-20 durable facts "
                         "(purpose, architecture, conventions, current state, gotchas), and "
                         "save_memory each with a one-line rule + full body. "
-                        "`memgit onboard` prints the complete brief."
+                        "Run `memgit onboard` first — it mines the repo's git history and "
+                        "manifests into a factual digest plus the complete seeding brief, "
+                        "so you read only what matters instead of crawling the tree."
                     )
                 return [TextContent(type="text", text=text)]
 

{memgit-0.3.0 → memgit-0.3.1}/memgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -193,10 +193,10 @@ Memory tools have a cold-start problem: install one halfway through a project an
 
 ```bash
 cd your-project
-memgit onboard          # prints the bootstrap brief
+memgit onboard          # mines the repo, 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."
+`onboard` first extracts a **repo digest** deterministically — git history (recent commit subjects, hot files/directories by churn, authors, branch, tags), detected stack from manifests, and the docs worth reading — using bounded, read-only probes that stay near-instant even on huge repositories. The brief then tells your AI agent exactly what to do with it: read only the listed files (no tree crawling), 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.
 

{memgit-0.3.0 → memgit-0.3.1}/memgit.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 memgit/__init__.py
 memgit/cli.py
+memgit/gitdigest.py
 memgit/graph.py
 memgit/http_server.py
 memgit/importer.py

{memgit-0.3.0 → memgit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memgit"
-version = "0.3.0"
+version = "0.3.1"
 description = "Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more"
 readme = "README.md"
 requires-python = ">=3.11"

{memgit-0.3.0 → memgit-0.3.1}/tests/test_v030.py

@@ -281,6 +281,85 @@ class TestCli:
         assert msg == "sync: +1 (brand-new)"
 
 
+# ── git digest (onboarding intelligence) ────────────────────────────────────
+
+def _make_git_repo(root: Path):
+    import subprocess
+    def g(*args):
+        subprocess.run(["git"] + list(args), cwd=root, capture_output=True,
+                       env={"GIT_AUTHOR_NAME": "Tester", "GIT_AUTHOR_EMAIL": "t@t",
+                            "GIT_COMMITTER_NAME": "Tester", "GIT_COMMITTER_EMAIL": "t@t",
+                            "PATH": os.environ["PATH"], "HOME": os.environ.get("HOME", "")})
+    g("init", "-q", "-b", "main")
+    (root / "README.md").write_text("# proj")
+    (root / "pyproject.toml").write_text("[project]\nname='x'")
+    (root / "src").mkdir()
+    (root / "src" / "app.py").write_text("print(1)")
+    g("add", "-A")
+    g("commit", "-qm", "initial scaffold")
+    (root / "src" / "app.py").write_text("print(2)")
+    g("add", "-A")
+    g("commit", "-qm", "fix: app output")
+
+
+class TestGitDigest:
+    def test_digest_extracts_facts(self, tmp_path):
+        from memgit.gitdigest import build_digest
+        _make_git_repo(tmp_path)
+        d = build_digest(tmp_path)
+        assert d["has_git"] is True
+        assert d["branch"] == "main"
+        assert d["commit_count"] == 2
+        assert "fix: app output" in d["recent_subjects"]
+        assert "README.md" in d["docs"]
+        assert "Python" in d["stacks"]
+        assert "src" in d["hot_dirs"]
+
+    def test_digest_without_git(self, tmp_path):
+        from memgit.gitdigest import build_digest
+        (tmp_path / "README.md").write_text("# hi")
+        d = build_digest(tmp_path)
+        assert d["has_git"] is False
+        assert d["docs"] == ["README.md"]
+
+    def test_format_digest_renders(self, tmp_path):
+        from memgit.gitdigest import build_digest, format_digest
+        _make_git_repo(tmp_path)
+        out = format_digest(build_digest(tmp_path))
+        assert "Read these first: README.md" in out
+        assert "Stack: Python" in out
+        assert "fix: app output" in out
+
+    def test_onboard_embeds_digest(self, tmp_path, monkeypatch):
+        _make_git_repo(tmp_path)
+        monkeypatch.chdir(tmp_path)
+        Repository.init(tmp_path)
+        r = CliRunner()
+        res = r.invoke(cli, ["onboard", "--project", "MyProj"])
+        assert res.exit_code == 0
+        assert "Repo digest" in res.output
+        assert "trust it, don't re-derive" in res.output
+        assert "do NOT crawl the tree" in res.output
+
+    def test_onboard_json_digest(self, tmp_path, monkeypatch):
+        import json
+        _make_git_repo(tmp_path)
+        monkeypatch.chdir(tmp_path)
+        Repository.init(tmp_path)
+        r = CliRunner()
+        res = r.invoke(cli, ["onboard", "--project", "MyProj", "--json"])
+        d = json.loads(res.output)
+        assert d["project"] == "MyProj" and d["has_git"] is True
+
+    def test_onboard_no_git_falls_back_generic(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        Repository.init(tmp_path)
+        r = CliRunner()
+        res = r.invoke(cli, ["onboard", "--project", "MyProj"])
+        assert res.exit_code == 0
+        assert "git log --oneline -30" in res.output  # generic reading plan
+
+
 # ── MCP project detection ────────────────────────────────────────────────────
 
 class TestMcpDetect: