pygim 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygim
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Full Python Gimmicks project with all of its sub-projects.
 Project-URL: homepage, https://github.com/Debith/pygim
 Project-URL: documentation, https://readthedocs.org/projects/pygim/

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/_pygim/_cli/_cli_app.py

@@ -9,6 +9,7 @@ from subprocess import Popen, DEVNULL
 import sys
 import shutil
 import functools
+from typing import Optional
 from pathlib import Path
 from dataclasses import dataclass
 from importlib import import_module
@@ -93,19 +94,8 @@ class GimmicksCliApp:
         except (FileNotFoundError, _docs_serve.ServeError) as exc:
             raise click.ClickException(str(exc)) from exc
 
-    def memory_init(self, *, root: str) -> None:
-        """Create a memory repository at *root* with the base vocabulary."""
-        from pygim.memory import Memory
-
-        try:
-            Memory.init(root)
-        except RuntimeError as exc:
-            raise click.ClickException(str(exc)) from exc
-        m = Memory(root)
-        click.echo(f"created {m.root} at v{m.version} — add a pack under taxonomy/, or start with the base")
-
-    def memory_mcp(self, *, root: str) -> None:
-        """Serve the repository at *root* over MCP on stdio."""
+    def memory_mcp(self, *, root: Optional[str]) -> None:
+        """Serve the project's store over MCP on stdio; the server starts even without one."""
         from _pygim._mcp import memory as server
         from pygim.memory import VocabularyError
 
@@ -114,33 +104,94 @@ class GimmicksCliApp:
         except (RuntimeError, VocabularyError) as exc:
             raise click.ClickException(str(exc)) from exc
 
-    def memory_ingest(self, *, corpus: str, root: str) -> None:
-        """Ingest a hand-written corpus file into the repository at *root*."""
+    @staticmethod
+    def _store(root: Optional[str]) -> str:
+        """The store for this project, or a ClickException that says how to make one."""
+        from _pygim._mcp import _stores
+
+        found = _stores.find(root)
+        if found is None or not found.exists:
+            raise click.ClickException(_stores.guidance())
+        return str(found.root)
+
+    def memory_setup(self, *, kind: Optional[str], name: Optional[str], path: Optional[str], source: Optional[str],
+                     register: bool) -> None:
+        """Find or create the project's store, point the clone at it, and register the server."""
+        from _pygim._mcp import _stores
+
+        cwd = Path.cwd()
+        try:
+            if kind == "user":
+                root = _stores.setup_user(cwd, name, Path(source) if source else None)
+                how = "a user-level store"
+            elif kind == "local":
+                root = _stores.setup_local(cwd, Path(source) if source else None)
+                how = "the project's own .memory"
+            elif kind == "branch":
+                root = _stores.setup_branch(cwd, Path(path) if path else None, Path(source) if source else None)
+                how = f"the `{_stores.BRANCH}` branch"
+            else:
+                found = _stores.find(cwd=cwd)
+                if found is None or not found.exists:
+                    raise click.ClickException("no store yet — choose where it lives: `oo memory setup --user` "
+                                               "(your user data directory) or `oo memory setup --branch` "
+                                               "(an orphan branch shared through git)")
+                root, how = found.root, found.how
+        except RuntimeError as exc:
+            raise click.ClickException(str(exc)) from exc
+        click.echo(f"store: {root} ({how})")
+        if _stores.git(["config", "--get", _stores.GIT_KEY], cwd):
+            click.echo(f"every worktree of this clone finds it through `git config {_stores.GIT_KEY}`")
+        local = Path(cwd) / ".mcp.json"
+        if local.is_file() and _stores.SERVER in local.read_text(encoding="utf-8"):
+            click.echo(f"note: {local} also defines `{_stores.SERVER}`; a project-scoped entry overrides the user one")
+        if register:
+            r = _stores.register()
+            click.echo(r.message)
+            if not r.ran and not r.message.startswith(f"`{_stores.SERVER}` is already"):
+                click.echo("  " + " ".join(r.command))
+
+    def memory_ingest(self, *, corpus: str, root: Optional[str]) -> None:
+        """Ingest a hand-written corpus file into the project's store."""
         from pygim.memory import Memory
 
-        result = Memory(root).ingest(corpus)
+        result = Memory(self._store(root)).ingest(corpus)
         click.echo(f"{result['added']} added, {result['superseded']} superseded, {result['unchanged']} unchanged")
         for line in result["refused"]:
             click.echo(f"  refused {line}")
         if result["refused"]:
             raise click.exceptions.Exit(1)
 
-    def memory_accept(self, *, memory: str, reason: str, root: str) -> None:
-        """Accept a generalisation in the repository at *root*."""
+    def memory_accept(self, *, memory: Optional[str], pack: Optional[str], reason: str, replace: bool,
+                      root: Optional[str]) -> None:
+        """Accept a generalisation (*memory*) or a drafted vocabulary pack (*pack*) in the project's store."""
         from pygim.memory import Memory
 
-        result = Memory(root).accept(memory, reason=reason)
+        if (memory is None) == (pack is None):
+            raise click.UsageError("accept one thing: a generalisation as MEMORY, or a vocabulary draft with --pack")
+        if pack is not None:
+            from _pygim._mcp import _packs
+
+            done = _packs.accept(Path(self._store(root)), Path(pack).resolve(), replace=replace)
+            if not done["ok"]:
+                raise click.ClickException(done["errors"])
+            click.echo(f"accepted pack `{done['pack']}`: {len(done['dimensions'])} dimension(s), {done['values']} value(s)"
+                       + (f"; {len(done['inventory'])} document(s) added to the inventory" if done["inventory"] else ""))
+            click.echo("a running MCP server picks it up at its next call")
+            return
+        result = Memory(self._store(root)).accept(memory, reason=reason)
         if not result["ok"]:
             raise click.ClickException(f"{result['refused']}: {result['message']}"
                                        + "".join(f"\n  {fact}" for fact in result["facts"]))
         click.echo(f"accepted {memory} — its instances fold from the next read (report: {result['report']})")
 
-    def memory_status(self, *, root: str) -> None:
+    def memory_status(self, *, root: Optional[str]) -> None:
         """Print where the repository at *root* stands."""
         from pygim.memory import Memory
 
-        info = Memory(root).session()
-        click.echo(f"{root}: v{info['version']}, {info['memories']} memories, vocabulary {info['taxonomy'][:12]}")
+        store = self._store(root)
+        info = Memory(store).session()
+        click.echo(f"{store}: v{info['version']}, {info['memories']} memories, vocabulary {info['taxonomy'][:12]}")
         for r in info["reviews"]:
             click.echo(f"  review ({r['kind']}): {r['text']}")
         for p in info["proposals"]:

pygim-0.1.0.dev2/src/_pygim/_mcp/_packs.py

@@ -0,0 +1,124 @@
+"""Drafted vocabulary packs and the citations they rest on.
+
+A pack drafted by the ``prepare-vocabulary`` prompt is a proposal until a person accepts it
+(overview §4.6). ``check`` loads a proposal beside the store's current vocabulary in a scratch
+store, so every error comes back by file and line without touching the real one; ``accept`` is
+the person's step that makes it live. ``cite`` turns a line of a project document into a locator
+— the passage digest a value carries, and the document's version for the inventory.
+
+Citation paths are relative to the project's root, not to the store: a store in a user directory
+or on the ``memory`` branch lives outside the checkout, and every worktree must resolve the same
+document from the same path.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List
+
+_PACK_NAME = re.compile(r"^pack:\s*([A-Za-z0-9_\-]+)\s*$", re.MULTILINE)
+_INVENTORY_ID = re.compile(r"^([A-Za-z0-9_.\-]+):\s*$", re.MULTILINE)
+
+
+def pack_name(text: str) -> str:
+    m = _PACK_NAME.search(text)
+    if not m:
+        raise ValueError("a pack starts with `pack: <domain>` — the domain's name is the pack's name")
+    return m.group(1)
+
+
+def check(store: Path, proposal: Path) -> Dict[str, Any]:
+    """Loads *proposal* as ``taxonomy/pack-<name>.yaml`` beside the store's vocabulary, in a scratch
+    copy. ``ok`` with what the pack adds, or ``ok: False`` with the loader's messages, which name
+    the proposal's own path and line."""
+    from pygim.memory import Memory, VocabularyError
+
+    text = proposal.read_text(encoding="utf-8")
+    try:
+        name = pack_name(text)
+    except ValueError as exc:
+        return {"ok": False, "errors": f"{proposal}:1: {exc}"}
+    target = f"pack-{name}.yaml"
+    with tempfile.TemporaryDirectory(prefix="pygim-pack-check-") as tmp:
+        scratch = Path(tmp) / "store"
+        Memory.init(str(scratch))
+        for existing in sorted((store / "taxonomy").glob("*.yaml")):
+            shutil.copyfile(existing, scratch / "taxonomy" / existing.name)
+        (scratch / "taxonomy" / target).write_text(text, encoding="utf-8")
+        try:
+            memory = Memory(str(scratch))
+        except VocabularyError as exc:
+            message = str(exc).replace(str(scratch / "taxonomy" / target), str(proposal)).replace(f"taxonomy/{target}", str(proposal))
+            return {"ok": False, "errors": message}
+        dims = [d for d in memory.vocabulary()["dimensions"] if d.get("pack") == name]
+        del memory
+    return {"ok": True, "pack": name, "dimensions": [d["name"] for d in dims],
+            "values": sum(sum(1 for v in d["values"] if not v.get("any")) for d in dims),
+            "replaces": (store / "taxonomy" / target).exists()}
+
+
+def accept(store: Path, proposal: Path, replace: bool = False) -> Dict[str, Any]:
+    """A person's step: checks the proposal, copies it to ``taxonomy/pack-<name>.yaml``, and adds the
+    documents of an ``inventory.yaml`` beside it to ``sources/inventory.yaml``. A pack of that name
+    already live is replaced only when asked."""
+    result = check(store, proposal)
+    if not result["ok"]:
+        return result
+    if result["replaces"] and not replace:
+        return {"ok": False, "errors": f"taxonomy/pack-{result['pack']}.yaml is already live — pass --replace to replace it"}
+    shutil.copyfile(proposal, store / "taxonomy" / f"pack-{result['pack']}.yaml")
+    result["inventory"] = _merge_inventory(store, proposal.parent / "inventory.yaml")
+    return result
+
+
+def _merge_inventory(store: Path, drafted: Path) -> List[str]:
+    """Appends the drafted inventory's documents that the store's inventory lacks; returns their ids."""
+    if not drafted.is_file():
+        return []
+    live = store / "sources" / "inventory.yaml"
+    live.parent.mkdir(parents=True, exist_ok=True)
+    have = set(_INVENTORY_ID.findall(live.read_text(encoding="utf-8"))) if live.is_file() else set()
+    blocks = re.split(r"(?m)^(?=[A-Za-z0-9_.\-]+:\s*$)", drafted.read_text(encoding="utf-8"))
+    added, keep = [], []
+    for block in blocks:
+        m = _INVENTORY_ID.match(block)
+        if m and m.group(1) not in have:
+            added.append(m.group(1))
+            keep.append(block.rstrip() + "\n")
+    if added:
+        header = "" if live.is_file() else "# The documents this vocabulary cites. Paths are relative to the project's root.\n"
+        with live.open("a", encoding="utf-8") as fh:
+            fh.write(header + "".join(keep))
+    return added
+
+
+def doc_id(relative: Path) -> str:
+    """A stable, readable id for a document: its project-relative path with separators as dashes."""
+    stem = relative.with_suffix("") if relative.suffix in (".md", ".rst", ".txt") else relative
+    return re.sub(r"[^A-Za-z0-9_.]+", "-", stem.as_posix()).strip("-").lower()
+
+
+def cite(project: Path, path: str, line: int, lines: int = 1) -> Dict[str, Any]:
+    """A locator into a project document: the passage at *line* (1-based) for *lines* lines."""
+    from pygim.memory import digest
+
+    file = (project / path).resolve() if not Path(path).is_absolute() else Path(path).resolve()
+    try:
+        relative = file.relative_to(project.resolve())
+    except ValueError:
+        raise ValueError(f"{file} is outside the project {project} — cite the project's own documents") from None
+    # \r\n is a line ending, never part of a line, as for hand-written memories (corpus.h): a checkout
+    # with Windows line endings must cite the same passage, and the same version, as one without.
+    content = file.read_bytes().replace(b"\r\n", b"\n")
+    text = content.decode("utf-8").split("\n")
+    if line < 1 or line + lines - 1 > len(text):
+        raise ValueError(f"{relative} has {len(text)} lines; line {line} for {lines} is out of range")
+    passage = "\n".join(text[line - 1:line - 1 + lines])
+    doc = doc_id(relative)
+    return {
+        "source": {"doc": doc, "line": line, "lines": lines, "passage": digest(passage.encode("utf-8"))},
+        "inventory": {"id": doc, "kind": "text", "path": relative.as_posix(), "version": digest(content)},
+        "text": passage,
+    }

pygim-0.1.0.dev2/src/_pygim/_mcp/_stores.py

@@ -0,0 +1,232 @@
+"""Where a project's memory lives, and how a machine is set up to use it.
+
+A store is found, in order, by:
+
+1. an explicit root (``--root``);
+2. ``$PYGIM_MEMORY_ROOT``;
+3. ``git config pygim.memory`` — git keeps it in the clone's shared config, so every worktree of
+   the project finds the same store;
+4. a ``.memory`` directory found by walking up from the working directory.
+
+``oo memory setup`` writes that git config, creates the store — in a user-level directory, or
+on an orphan ``memory`` branch checked out as a worktree of its own — and registers the MCP
+server with Claude Code at user scope, without a root, so it finds each project's store from the
+directory it is started in. Nothing here imports click; the CLI and the MCP server both use it.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+ENV = "PYGIM_MEMORY_ROOT"
+GIT_KEY = "pygim.memory"
+LOCAL = ".memory"
+BRANCH = "memory"
+SERVER = "pygim-memory"
+
+
+@dataclass(frozen=True)
+class Found:
+    """A store's root and how it was found — shown to the user, since four places can name one."""
+    root: Path
+    how: str
+
+    @property
+    def exists(self) -> bool:
+        return is_store(self.root)
+
+
+def is_store(path: Path) -> bool:
+    return (path / "taxonomy" / "base.yaml").is_file()
+
+
+def git(args: Sequence[str], cwd: Path) -> Optional[str]:
+    """``git <args>`` in *cwd*: its stripped output, or None when git is missing or it fails."""
+    try:
+        done = subprocess.run(["git", *args], cwd=str(cwd), capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return done.stdout.strip() if done.returncode == 0 else None
+
+
+def main_worktree(cwd: Path) -> Optional[Path]:
+    """The clone's main worktree — the directory that holds its ``.git`` — from any of its worktrees."""
+    common = git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd)
+    if not common:
+        return None
+    common_dir = Path(common)
+    return common_dir.parent if common_dir.name == ".git" else Path(git(["rev-parse", "--show-toplevel"], cwd) or cwd)
+
+
+def project_root(cwd: Path) -> Path:
+    """What a source citation's path is relative to: this worktree's top, or *cwd* outside git."""
+    top = git(["rev-parse", "--show-toplevel"], cwd)
+    return Path(top) if top else cwd
+
+
+def find(explicit: Optional[str] = None, cwd: Optional[Path] = None) -> Optional[Found]:
+    """The store for *cwd*, by the order in the module docstring, or None when nothing names one.
+    The first three are returned whether or not a store exists there yet — setup creates it."""
+    cwd = Path(cwd or os.getcwd()).resolve()
+    if explicit:
+        return Found(Path(explicit).expanduser().resolve(), "--root")
+    if os.environ.get(ENV):
+        return Found(Path(os.environ[ENV]).expanduser().resolve(), "$" + ENV)
+    configured = git(["config", "--get", GIT_KEY], cwd)
+    if configured:
+        path = Path(configured).expanduser()
+        if not path.is_absolute():
+            path = (main_worktree(cwd) or cwd) / path
+        return Found(path.resolve(), "git config " + GIT_KEY)
+    for directory in (cwd, *cwd.parents):
+        if is_store(directory / LOCAL):
+            return Found((directory / LOCAL).resolve(), LOCAL + " above the working directory")
+    return None
+
+
+def guidance(cwd: Optional[Path] = None) -> str:
+    """What to tell someone whose project has no store yet."""
+    where = find(cwd=cwd)
+    if where and not where.exists:
+        return f"{where.root} (from {where.how}) is not a memory store yet — run `oo memory setup` in the project"
+    return ("no memory store for this project — run `oo memory setup --user` (a store in your user directory) "
+            "or `oo memory setup --branch` (an orphan `memory` branch shared through git) in the project; "
+            "`--local` keeps one inside the project instead")
+
+
+# ── setup ─────────────────────────────────────────────────────────────────────
+
+
+def user_data_dir() -> Path:
+    """Where user-level stores live: the platform's per-user data directory, under pygim/memory."""
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+    return base / "pygim" / "memory"
+
+
+def project_name(cwd: Path) -> str:
+    main = main_worktree(cwd)
+    return (main or cwd).name
+
+
+def point_git_at(root: Path, cwd: Path) -> bool:
+    """Record *root* in the clone's shared git config; False outside git."""
+    if git(["rev-parse", "--git-dir"], cwd) is None:
+        return False
+    return git(["config", GIT_KEY, str(root)], cwd) is not None
+
+
+def create(root: Path, source: Optional[Path] = None) -> None:
+    """A new store at *root*: empty, or a copy of the store at *source* — every file but ``local/``,
+    which is one clone's alone. The copy is a new clone of the same history: its next write starts a
+    new audit file, and the old ones keep replaying beside it."""
+    from pygim.memory import Memory
+
+    if source is None:
+        Memory.init(str(root))
+        return
+    if not is_store(source):
+        raise RuntimeError(f"{source} is not a memory store — nothing to copy")
+    shutil.copytree(source, root, ignore=shutil.ignore_patterns("local"), dirs_exist_ok=True)
+    (root / "local").mkdir(exist_ok=True)
+
+
+def setup_user(cwd: Path, name: Optional[str] = None, source: Optional[Path] = None) -> Path:
+    """A store under the user data directory, named for the project, and git pointed at it."""
+    root = user_data_dir() / (name or project_name(cwd))
+    if not is_store(root):
+        create(root, source)
+    point_git_at(root, cwd)
+    return root
+
+
+def setup_local(cwd: Path, source: Optional[Path] = None) -> Path:
+    """A store inside the project, as ``.memory`` at this worktree's top, committed with the code. Git
+    config is left alone: this store belongs to the branch that carries it, and other worktrees on
+    other branches find theirs, or none."""
+    root = project_root(cwd) / LOCAL
+    if not is_store(root):
+        create(root, source)
+    return root
+
+
+def setup_branch(cwd: Path, path: Optional[Path] = None, source: Optional[Path] = None) -> Path:
+    """A store on the orphan ``memory`` branch, checked out as its own worktree beside the main one.
+    An existing local or remote-tracking ``memory`` branch is checked out rather than created — a
+    second machine gets the project's memory with ``git fetch`` and this call."""
+    main = main_worktree(cwd)
+    if main is None:
+        raise RuntimeError(f"{cwd} is not in a git repository — use `oo memory setup --user` instead")
+    root = (path or main.parent / f"{main.name}-{BRANCH}").expanduser().resolve()
+    if is_store(root):
+        point_git_at(root, cwd)
+        return root
+    if root.exists() and any(root.iterdir()):
+        raise RuntimeError(f"{root} exists and is not a memory store — choose another --path")
+    has_local = git(["show-ref", "--verify", "--quiet", f"refs/heads/{BRANCH}"], cwd) is not None
+    has_remote = git(["show-ref", "--verify", "--quiet", f"refs/remotes/origin/{BRANCH}"], cwd) is not None
+    if has_local:
+        _require(git(["worktree", "add", str(root), BRANCH], cwd), f"git worktree add {root} {BRANCH}")
+    elif has_remote:
+        _require(git(["worktree", "add", "--track", "-b", BRANCH, str(root), f"origin/{BRANCH}"], cwd),
+                 f"git worktree add --track -b {BRANCH} {root} origin/{BRANCH}")
+    else:
+        _require(git(["worktree", "add", "--orphan", "-b", BRANCH, str(root)], cwd),
+                 f"git worktree add --orphan -b {BRANCH} {root}")
+        create(root, source)
+        git(["add", "-A"], root)
+        if git(["commit", "-m", "memory: the store, as initialised by oo memory setup"], root) is None:
+            raise RuntimeError(f"created the store in {root}, but could not commit it — commit it there yourself")
+    if not is_store(root):
+        raise RuntimeError(f"the {BRANCH} branch checked out in {root} holds no memory store")
+    point_git_at(root, cwd)
+    return root
+
+
+def _require(result: Optional[str], what: str) -> None:
+    if result is None:
+        raise RuntimeError(f"`{what}` failed — run it yourself to see why")
+
+
+# ── registration ──────────────────────────────────────────────────────────────
+
+
+def server_command() -> List[str]:
+    """How to start this installation's server, with no root: it finds each project's store from the
+    directory the host starts it in. Absolute, so the host needs nothing on its PATH."""
+    scripts = Path(sys.executable).parent
+    for candidate in (scripts / "oo", scripts / "oo.exe", scripts / "Scripts" / "oo.exe"):
+        if candidate.is_file():
+            return [str(candidate), "memory", "mcp"]
+    return [sys.executable, "-c", "from pygim.__main__ import cli_oo; cli_oo()", "memory", "mcp"]
+
+
+@dataclass(frozen=True)
+class Registration:
+    ran: bool          # True when `claude mcp add` ran here
+    command: List[str]
+    message: str
+
+
+def register() -> Registration:
+    """Registers the server with Claude Code at user scope, so every project and worktree gets it.
+    Without the ``claude`` command on PATH, returns the command to run instead of guessing a config file."""
+    command = ["claude", "mcp", "add", "--scope", "user", SERVER, "--", *server_command()]
+    claude = shutil.which("claude")
+    if claude is None:
+        return Registration(False, command, "the `claude` command is not on PATH — run this where it is")
+    if subprocess.run([claude, "mcp", "get", SERVER], capture_output=True, text=True).returncode == 0:
+        return Registration(False, command, f"`{SERVER}` is already registered — `claude mcp remove {SERVER} -s user` to replace it")
+    done = subprocess.run([claude, *command[1:]], capture_output=True, text=True)
+    if done.returncode != 0:
+        return Registration(False, command, "`claude mcp add` failed: " + (done.stderr or done.stdout).strip())
+    return Registration(True, command, f"registered `{SERVER}` for every project at user scope")

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/_pygim/_mcp/memory.py

@@ -12,12 +12,18 @@ is the overview's §4.5.
 """
 from __future__ import annotations
 
+import datetime
 import json
+import os
 import sys
+from pathlib import Path
 from typing import Any, Callable, Dict, IO, List, Optional
 
+from . import _packs, _stores
+
 PROTOCOL_VERSION = "2025-06-18"
 SERVER_NAME = "pygim-memory"
+STANDING_TOKENS = 2000  # how much preference text the startup instructions may carry
 
 INSTRUCTIONS = """\
 A problem-space memory: knowledge is found by the kind of problem being solved,
@@ -40,6 +46,10 @@ not by similarity to the prompt.
    `generalises` naming them, and record `lessons`. Nothing is retired, and a
    generalisation folds its instances only after the user accepts it themselves
    with `oo memory accept` — there is no tool for that, on purpose.
+6. A project with no vocabulary pack of its own starts with the `prepare-vocabulary`
+   prompt (the user accepts the draft with `oo memory accept --pack`), then
+   `seed-memories`. If a tool says there is no store, tell the user to run
+   `oo memory setup` in the project.
 """
 
 CONSOLIDATE = """\
@@ -69,6 +79,89 @@ Consolidate what this session has written into memory so far.
    accept it for them.
 """
 
+PACK_SHAPE = """\
+pack: {domain}
+entry: {{brief: ..., when: ..., when_not: ..., example: ...}}       # the domain itself: domain={domain}
+dimensions:
+  <dimension>:
+    role: hard            # hard: filters by default. soft: only orders
+    weight: 1.0
+    entry: {{brief: ..., full: ..., when: ..., when_not: ..., example: ...}}
+    values:
+      <value>:
+        entry: {{brief: ..., when: ..., when_not: ..., example: ...}}
+        source: {{doc: <id from cite>, line: 12, lines: 1, passage: <digest from cite>}}
+extends:                  # this domain's values for the base dimensions
+  artifact:
+    <value>: {{entry: {{...}}, source: {{...}}}}
+  task:
+    <value>: {{entry: {{...}}}}
+  tier:
+    <value>: {{entry: {{...}}}}"""
+
+PREPARE_VOCABULARY = """\
+Prepare the vocabulary for the `{domain}` domain: a pack drafted from this project's own
+documents, which becomes the vocabulary only when the user accepts it.
+
+The base vocabulary (domain, artifact, task, kind, tier) ships with every store. A pack adds
+this domain's values to artifact, task and tier, and dimensions of its own. Every memory will be
+found through these tags, so the vocabulary is the first thing a project needs.
+
+1. Call `session` (it gives the store's `root` and the `project` root) and `vocabulary`.
+2. Inventory the sources. The project's documents are the only guaranteed input: the README,
+   design documents, guides, and the names the source tree itself uses — directories, modules,
+   manifests. List them. Anything you compute from them, such as a term count, is derived, not a source.
+3. Find the questions. A dimension is one question with a closed list of answers, independent of
+   the others. Make one hard only when knowledge under one answer should never surface while
+   working under another, as a subsystem's should not; everything else is soft. Look first for
+   closed lists the sources already label — directory names, manifest kinds, document types:
+   they cost nothing and classify reliably.
+4. Name every value in the project's ubiquitous language. Count how the sources name each
+   concept and use their word; never coin one. The dimension and the value together should read
+   as a term the project uses. Give each value a locator with `cite`, and list the values nothing
+   cites rather than inventing a source.
+5. Write a codebook entry for every dimension and value: brief, full (dimensions), when,
+   when_not, example. An artifact value names what a thing is, never how it is used — given
+   only the thing, two readers should agree on it.
+6. Reconcile every list you derived against the sources' complete list: what is in both, what
+   the sources have that you left out, and what you have that the sources do not. Never present
+   a derived list alone.
+7. Probe coverage: take one real item for every artifact value and try to tag it. Note what
+   cannot be tagged — that is where the vocabulary is thin.
+8. Draft into the store, under `taxonomy/studies/{today}-{domain}/`:
+   - `proposal/pack-{domain}.yaml`, in this shape:
+{pack_shape}
+   - `proposal/inventory.yaml`: one entry per cited document, from `cite`'s `inventory` —
+     `<id>:` then `kind`, `path` (relative to the project root) and `version`.
+   - `report.md`: the sources, each dimension and why it exists, the counts that chose each name,
+     the uncited values, the reconciliation, the coverage probe, and your open questions.
+9. Call `check_pack` on the proposal and fix every error it names, by file and line.
+10. Tell the user where the report is, and that the pack becomes the vocabulary only when they
+    run `oo memory accept --pack <path to the proposal>`. Do not copy it into taxonomy/ yourself.
+"""
+
+SEED_MEMORIES = """\
+Seed this project's memory with what is already known, so the first working session does not
+start from nothing.
+
+1. Call `session` and `vocabulary`. If no pack names this project's domain yet, stop and suggest
+   the `prepare-vocabulary` prompt first: a memory tagged from the base vocabulary alone is hard
+   to find again.
+2. Find durable knowledge in the project's documents and history: decisions and their reasons,
+   conventions the code follows, how recurring tasks are done (adding a module, releasing,
+   testing), known pitfalls. Skip what a document already states plainly — sources are cited,
+   not copied. A memory earns its place by saying what a reader would otherwise rediscover.
+3. For each one, `read` its space first, then decide: nothing covers it, so `remember`;
+   something says less or says it wrong, so `remember` superseding it; something already says
+   exactly this, so `learn`. Answer every hard dimension, and `cite` the passage it rests on.
+4. Write how a recurring task is done as a procedure (kind=procedure, one per artifact and
+   task), a choice and its reason as a decision, and a rule of thumb as a principle only when
+   several cases show it.
+5. Write concretely — the case and where it came from. Leave patterns for a later `consolidate`.
+6. Record `lessons`: what you seeded, what you left out and why, and the gaps — knowledge the
+   vocabulary could not tag. Tell the user the report's path.
+"""
+
 PROMPTS: List[Dict[str, Any]] = [
     {
         "name": "consolidate",
@@ -76,8 +169,35 @@ PROMPTS: List[Dict[str, Any]] = [
                        "any pattern several memories share. Nothing is retired.",
         "arguments": [],
     },
+    {
+        "name": "prepare-vocabulary",
+        "description": "Draft this project's vocabulary pack from its own documents, with a study report, "
+                       "for the user to accept with `oo memory accept --pack`.",
+        "arguments": [{"name": "domain", "description": "The domain's name, which is the pack's name "
+                                                        "(default: the project directory's name).", "required": False}],
+    },
+    {
+        "name": "seed-memories",
+        "description": "Record what the project's documents and history already know — decisions, conventions, "
+                       "procedures — as the store's first memories.",
+        "arguments": [],
+    },
 ]
-_PROMPT_TEXT = {"consolidate": CONSOLIDATE}
+
+
+def _domain_of(arguments: Dict[str, Any], server: "MemoryServer") -> str:
+    given = str(arguments.get("domain") or "").strip()
+    name = given or _stores.project_name(server._cwd)
+    return "".join(c if c.isalnum() else "_" for c in name.lower()).strip("_") or "project"
+
+
+_PROMPT_TEXT: Dict[str, Callable[[Dict[str, Any], "MemoryServer"], str]] = {
+    "consolidate": lambda args, server: CONSOLIDATE,
+    "prepare-vocabulary": lambda args, server: PREPARE_VOCABULARY.format(
+        domain=_domain_of(args, server), today=datetime.date.today().isoformat(),
+        pack_shape="\n".join("       " + line for line in PACK_SHAPE.format(domain=_domain_of(args, server)).split("\n"))),
+    "seed-memories": lambda args, server: SEED_MEMORIES,
+}
 
 _REF = {"type": "string", "description": "A memory: #n from a read or show, or at least 8 characters of its key."}
 _TAGS = {"type": "array", "items": {"type": "string"}, "description": "Qualified tags, dimension=value, from the vocabulary."}
@@ -199,18 +319,51 @@ TOOLS: List[Dict[str, Any]] = [
                        "adding it to a pack file under taxonomy/; the asking memories are then linked on the next start.",
         "inputSchema": _schema({}),
     },
+    {
+        "name": "cite",
+        "description": "A locator into one of this project's documents: the passage digest a vocabulary value or a "
+                       "memory carries, the document's inventory entry, and the passage's text. Paths are relative "
+                       "to the project root.",
+        "inputSchema": _schema({
+            "path": {"type": "string", "description": "The document, relative to the project root."},
+            "line": {"type": "integer", "minimum": 1},
+            "lines": {"type": "integer", "minimum": 1, "description": "How many lines the passage spans (default 1)."},
+        }, ["path", "line"]),
+    },
+    {
+        "name": "check_pack",
+        "description": "Loads a drafted pack beside the store's vocabulary in a scratch copy and reports every error "
+                       "by file and line, or what the pack adds. Nothing live changes; the user accepts a pack.",
+        "inputSchema": _schema({"path": {"type": "string",
+                                         "description": "The proposal, relative to the store root or the project root."}},
+                               ["path"]),
+    },
 ]
 
 
-class MemoryServer:
-    """Answers MCP messages for one repository. `handle` takes one decoded
-    message and returns the response to write, or None for a notification."""
+class NoStore(RuntimeError):
+    """The project has no memory store yet; the message says how to make one."""
 
-    def __init__(self, memory: Any) -> None:
-        self.memory = memory
+
+class MemoryServer:
+    """Answers MCP messages for one project's store. `handle` takes one decoded
+    message and returns the response to write, or None for a notification.
+
+    The store is found lazily (see `_stores.find`), so the server starts in a project
+    that has none and answers with setup guidance until one exists. It reopens the
+    store when a vocabulary file under taxonomy/ changes, so an accepted pack is live
+    at the next call without restarting the server."""
+
+    def __init__(self, memory: Any = None, *, root: Optional[str] = None, cwd: Optional[Path] = None) -> None:
+        self._memory = memory
+        self._root = root
+        self._cwd = Path(cwd or os.getcwd())
+        self._stamp = self._taxonomy_stamp() if memory is not None else None
         self.session: Optional[int] = None
         self.turn = 0
         self._calls: Dict[str, Callable[[Dict[str, Any]], Any]] = {
+            "cite": lambda a: _packs.cite(_stores.project_root(self._cwd), a["path"], int(a["line"]), int(a.get("lines", 1))),
+            "check_pack": lambda a: _packs.check(Path(self.memory.root), self._store_path(a["path"])),
             "session": self._session,
             "vocabulary": lambda a: self.memory.vocabulary(),
             "read": lambda a: self.memory.read(a["hard"], a.get("soft", []), max=a.get("max", 8),
@@ -229,6 +382,67 @@ class MemoryServer:
             "proposals": lambda a: self.memory.proposals(),
         }
 
+    # ── the store ───────────────────────────────────────────────────────────
+
+    @property
+    def memory(self) -> Any:
+        from pygim.memory import Memory
+
+        if self._memory is None:
+            found = _stores.find(self._root, self._cwd)
+            if found is None or not found.exists:
+                raise NoStore(_stores.guidance(self._cwd))
+            self._memory = Memory(str(found.root))
+            self._stamp = self._taxonomy_stamp()
+        elif self._taxonomy_stamp() != self._stamp:
+            self._memory = Memory(self._memory.root)  # a broken pack raises here, by file and line, and nothing is swapped
+            self._stamp = self._taxonomy_stamp()
+        return self._memory
+
+    def _standing(self) -> str:
+        """The project's standing knowledge, appended to the instructions a host loads into every
+        session: each preference in full, and the title of each procedure — a read naming its
+        artifact and task places its steps first anyway. Nothing is recorded as read. Empty when
+        there is no store, or nothing of either kind; capped at STANDING_TOKENS, naming what it leaves out."""
+        try:
+            preferences = self.memory.heads(["kind=preference"])
+            procedures = self.memory.heads(["kind=procedure"])
+        except Exception:  # no store yet, or a vocabulary that will not load: the tools will say so
+            return ""
+        if not preferences and not procedures:
+            return ""
+        out = ["", "Standing knowledge from this project's memory, as of this server's start. It applies to",
+               "every task, so it is given here instead of waiting for a read."]
+        if preferences:
+            out += ["", "Preferences:"]
+            used, left_out = 0, []
+            for p in preferences:
+                if used + p["tokens"] > STANDING_TOKENS:
+                    left_out.append(f"{p['memory']} {p['title']}")
+                    continue
+                used += p["tokens"]
+                body = p["text"].strip().replace("\n", "\n  ")
+                out.append(f"- {p['memory']} {p['title']}: {body}")
+            if left_out:
+                out.append("- not shown, for length (`show` them): " + "; ".join(left_out))
+        if procedures:
+            out += ["", "Procedures — a read naming their artifact and task places the steps first:"]
+            for p in procedures:
+                where = " ".join(t for t in p["tags"] if t.startswith(("artifact=", "task=")))
+                out.append(f"- {p['memory']} {p['title']} — {where}")
+        return "\n".join(out) + "\n"
+
+    def _taxonomy_stamp(self) -> Any:
+        files = sorted(Path(self._memory.root, "taxonomy").glob("*.yaml"))
+        return tuple((f.name, f.stat().st_mtime_ns, f.stat().st_size) for f in files)
+
+    def _store_path(self, path: str) -> Path:
+        p = Path(path).expanduser()
+        if p.is_absolute():
+            return p
+        in_store = Path(self.memory.root) / p
+        return in_store if in_store.exists() else _stores.project_root(self._cwd) / p
+
     # ── tools ───────────────────────────────────────────────────────────────
 
     def _session_no(self) -> int:
@@ -239,6 +453,8 @@ class MemoryServer:
     def _session(self, _: Dict[str, Any]) -> Any:
         info = self.memory.session()
         self.session = int(info["session"])
+        info["root"] = self.memory.root
+        info["project"] = str(_stores.project_root(self._cwd))
         return info
 
     def _remember(self, a: Dict[str, Any]) -> Any:
@@ -261,7 +477,7 @@ class MemoryServer:
                 "protocolVersion": requested,
                 "capabilities": {"tools": {"listChanged": False}, "prompts": {"listChanged": False}},
                 "serverInfo": {"name": SERVER_NAME, "version": _version()},
-                "instructions": INSTRUCTIONS,
+                "instructions": INSTRUCTIONS + self._standing(),
             })
         if method == "ping":
             return _result(mid, {})
@@ -273,11 +489,13 @@ class MemoryServer:
         if method == "prompts/list":
             return _result(mid, {"prompts": PROMPTS})
         if method == "prompts/get":
-            name = (msg.get("params") or {}).get("name", "")
-            text = _PROMPT_TEXT.get(name)
-            if text is None:
+            params = msg.get("params") or {}
+            name = params.get("name", "")
+            render = _PROMPT_TEXT.get(name)
+            if render is None:
                 return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": f"unknown prompt: {name}"}}
             meta = next(p for p in PROMPTS if p["name"] == name)
+            text = render(params.get("arguments") or {}, self)
             return _result(mid, {"description": meta["description"],
                                  "messages": [{"role": "user", "content": {"type": "text", "text": text}}]})
         return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"method not found: {method}"}}
@@ -291,6 +509,8 @@ class MemoryServer:
             return _text(f"unknown tool: {name}", error=True)
         try:
             result = fn(arguments)
+        except NoStore as exc:
+            return _text(f"{name}: {exc}", error=True)
         except KeyError as exc:
             return _text(f"{name}: missing argument {exc.args[0]!r}", error=True)
         except Exception as exc:  # the extension's messages already name file and line
@@ -333,10 +553,13 @@ def _version() -> str:
         return "0"
 
 
-def run(root: str, stdin: Optional[IO[str]] = None, stdout: Optional[IO[str]] = None) -> None:
-    """Serves the repository at *root* over stdio until stdin closes."""
-    from pygim.memory import Memory
-
-    memory = Memory(root)
-    print(f"{SERVER_NAME}: serving {memory.root} at v{memory.version}", file=sys.stderr)
-    MemoryServer(memory).serve(stdin or sys.stdin, stdout or sys.stdout)
+def run(root: Optional[str] = None, stdin: Optional[IO[str]] = None, stdout: Optional[IO[str]] = None) -> None:
+    """Serves this project's store over stdio until stdin closes. With no *root*, the store is found
+    from the working directory the host started the server in; with none at all the server still
+    starts, and answers with how to create one."""
+    found = _stores.find(root)
+    if found and found.exists:
+        print(f"{SERVER_NAME}: serving {found.root} (from {found.how})", file=sys.stderr)
+    else:
+        print(f"{SERVER_NAME}: {_stores.guidance()}", file=sys.stderr)
+    MemoryServer(root=root).serve(stdin or sys.stdin, stdout or sys.stdout)

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/_pygim_fast/memory/adapter/bindings.cpp

@@ -62,6 +62,9 @@ operation returns a plain dict, and a refused write is a result with
         .def("lessons", &Memory::lessons, py::arg("session"), py::arg("text"), py::kw_only(), py::arg("author") = "agent",
              "Records what a consolidation learnt and publishes it in reviews/session-<n>.md, beside the\n"
              "generalisations waiting for acceptance, the cases left, and the proposals raised.")
+        .def("heads", &Memory::heads, py::arg("tags"),
+             "Every head carrying any of `tags`, without recording a read — standing knowledge such as\n"
+             "kind=preference, handed to every session without touching usage counters.")
         .def("review", &Memory::review, py::arg("session"),
              "What one session wrote, in order, with what already generalises each memory — where a\n"
              "consolidation starts.")

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/pygim/__main__.py

@@ -93,22 +93,35 @@ def memory():
     """Problem-space memory: retrieval by the kind of problem being solved."""
 
 
-_ROOT = click.option("--root", default=".memory", show_default=True, type=click.Path(file_okay=False),
-                     help="The memory repository.")
-
-
-@memory.command("init")
-@_ROOT
-def memory_init(root):
-    """Create a repository with the base vocabulary."""
-    GimmicksCliApp().memory_init(root=root)
+_ROOT = click.option("--root", default=None, type=click.Path(file_okay=False),
+                     help="The memory store. Default: $PYGIM_MEMORY_ROOT, then `git config pygim.memory` "
+                          "(shared by every worktree), then a .memory above the working directory.")
+
+
+@memory.command("setup")
+@click.option("--user", "kind", flag_value="user", help="Create the store in your user data directory.")
+@click.option("--branch", "kind", flag_value="branch",
+              help="Keep the store on an orphan `memory` branch, checked out as a worktree of its own.")
+@click.option("--local", "kind", flag_value="local",
+              help="Keep the store in the project as .memory, committed with the code on this branch.")
+@click.option("--name", default=None, help="--user: the store's name (default: the project directory's name).")
+@click.option("--path", "path", default=None, type=click.Path(file_okay=False),
+              help="--branch: where to check the branch out (default: beside the main worktree).")
+@click.option("--from", "source", default=None, type=click.Path(exists=True, file_okay=False),
+              help="Start the new store as a copy of an existing one, such as a project's .memory.")
+@click.option("--no-register", is_flag=True, help="Do not register the MCP server with Claude Code.")
+def memory_setup(kind, name, path, source, no_register):
+    """Set this project and machine up to use a memory store: find or create the store, point every
+    worktree of the clone at it, and register the MCP server with Claude Code at user scope.
+    Run it again on another machine to join a project whose store already exists."""
+    GimmicksCliApp().memory_setup(kind=kind, name=name, path=path, source=source, register=not no_register)
 
 
 @memory.command("mcp")
 @_ROOT
 def memory_mcp(root):
-    """Serve the repository to an agent over MCP (stdio). Register it with
-    `claude mcp add memory -- oo memory mcp --root <absolute path>`."""
+    """Serve the project's store to an agent over MCP (stdio). With no --root it is found from the
+    directory the host starts it in, so one registration serves every project and worktree."""
     GimmicksCliApp().memory_mcp(root=root)
 
 
@@ -121,13 +134,17 @@ def memory_ingest(corpus, root):
 
 
 @memory.command("accept")
-@click.argument("memory_ref", metavar="MEMORY")
-@click.option("--reason", default="", help="Why the pattern holds; kept in the audit log.")
+@click.argument("memory_ref", metavar="[MEMORY]", required=False)
+@click.option("--pack", "pack", default=None, type=click.Path(exists=True, dir_okay=False),
+              help="Accept a drafted vocabulary pack instead: check it, make it live, add its cited documents.")
+@click.option("--reason", default="", help="MEMORY: why the pattern holds; kept in the audit log.")
+@click.option("--replace", is_flag=True, help="--pack: replace a pack of the same name that is already live.")
 @_ROOT
-def memory_accept(memory_ref, reason, root):
-    """Accept a generalisation: from the next read its instances fold under it.
-    A person runs this after reading reviews/session-<n>.md — the agent has no tool for it."""
-    GimmicksCliApp().memory_accept(memory=memory_ref, reason=reason, root=root)
+def memory_accept(memory_ref, pack, reason, replace, root):
+    """Accept what the agent drafted, after reading it: a generalisation (MEMORY, from
+    reviews/session-<n>.md), whose instances then fold under it; or a vocabulary pack (--pack, from
+    its study report), which then becomes the vocabulary. A person runs this — the agent has no tool for it."""
+    GimmicksCliApp().memory_accept(memory=memory_ref, pack=pack, reason=reason, replace=replace, root=root)
 
 
 @memory.command("status")

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/pygim/memory.pyi

@@ -33,6 +33,7 @@ class Memory:
                  cites: Sequence[str] = ..., proposals: List[Dict[str, str]] = ..., session: int = 0, turn: int = 0,
                  author: str = "agent") -> Dict[str, Any]: ...
     def review(self, session: int) -> Dict[str, Any]: ...
+    def heads(self, tags: Sequence[str]) -> List[Dict[str, Any]]: ...
     def accept(self, memory: str, *, reason: str = "", author: str = "human") -> Dict[str, Any]: ...
     def lessons(self, session: int, text: str, *, author: str = "agent") -> Dict[str, Any]: ...
     def merge(self, memories: Sequence[str], *, title: str, text: str, reason: str, tags: Sequence[str] = ...,

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/pygim.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygim
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Full Python Gimmicks project with all of its sub-projects.
 Project-URL: homepage, https://github.com/Debith/pygim
 Project-URL: documentation, https://readthedocs.org/projects/pygim/

{pygim-0.1.0.dev1 → pygim-0.1.0.dev2}/src/pygim.egg-info/SOURCES.txt

@@ -20,6 +20,8 @@ src/_pygim/_core/_typing.py
 src/_pygim/_core/protocols.py
 src/_pygim/_core/protocols.pyi
 src/_pygim/_mcp/__init__.py
+src/_pygim/_mcp/_packs.py
+src/_pygim/_mcp/_stores.py
 src/_pygim/_mcp/memory.py
 src/_pygim_fast/datagen/bindings.cpp
 src/_pygim_fast/each/bindings.cpp