corkern 2.0.0rc2__tar.gz

corkern-2.0.0rc2/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.corkern-v1.sentinel
+tmp.local/
+
+.env

corkern-2.0.0rc2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SCPG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

corkern-2.0.0rc2/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: corkern
+Version: 2.0.0rc2
+Summary: Collective knowledge for Claude Code: syncs its memory across projects, devices and people through a private git repository
+Author: SCPG
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,claude-code,git,knowledge-base,memory,sync
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: rich<14,>=13
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
+Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+> ⚠ **First test release — please do not use it yet.**
+> This is corkern's first upload to PyPI, published only to try the release process. It is
+> not meant for use. A proper version is planned for the coming weeks.
+
+# corkern
+
+**Collective knowledge for Claude Code — across projects, devices and people.**
+
+Claude Code keeps what it learns about you and your work in per-project memory files on one
+machine. corkern turns that into a synced knowledge base: a private git repository that every
+machine you use reads from and writes to, so what was learned in one project, on one laptop, is
+there the next time — anywhere.
+
+## Install — once per machine
+
+```
+uv tool install corkern        # or: pipx install corkern
+corkern setup --clone git@github.com:<you>/<your-private-knowledge-repo>.git
+corkern signing                # this machine's signing (+ push) key — asks first
+corkern init-device --apply    # wire Claude Code — shows the plan, asks first
+corkern doctor                 # check the installation
+```
+
+First machine without a knowledge repo yet: `corkern setup --create-github <you>/<name>` creates
+it as a **private** GitHub repository (`--new` keeps it local).
+
+corkern is meant to be installed exactly once per user, as a tool. A copy inside a project's
+virtual environment refuses to act (only `--version`, `--help`, `doctor` and `status` run) —
+`corkern doctor` shows every copy it finds.
+
+## What it does
+
+- **Syncs memories** between machines through a private git repository you own: pulled when a
+  Claude session starts, committed as memories are written, pushed when Claude finishes a reply.
+- **Brings context into every session**: open reminders, recent session notes and important
+  memories are shown to Claude at session start.
+- **Keeps concurrent edits side by side**: when two machines change the same memory, both versions
+  are kept (`<name>.conflict-<host>-<time>.md`) and reported. Memory indexes and the project
+  registry merge line by line.
+- **Stays out of Claude's way**: the hooks always exit successfully; sync problems are recorded and
+  shown by `corkern status`.
+- **One key per machine**: each machine signs its memory commits with its own key and can push
+  with a deploy key limited to the knowledge repository.
+- **Accepts only what your devices signed** (opt-in, `corkern trust`): incoming memories signed by
+  any other key, or unsigned, are held back until you accept them.
+- **Keeps secrets out of the repository**: before every commit, known token formats, private keys
+  and `password = …`-style values are replaced by a marker; the original stays on that machine.
+  The scan is pattern-based: a secret in a format it does not know can still get through.
+- **Warns when `MEMORY.md` outgrows what Claude Code loads** (200 lines / 25 KB).
+- **Uses Claude Code's own setting** (`autoMemoryDirectory`) to point each project's memory at the
+  knowledge repository.
+
+## What corkern writes on your machine
+
+| File | What corkern adds |
+|---|---|
+| `~/.config/corkern/machine.conf` | this machine's knowledge repository (machine-local) |
+| `~/.local/share/corkern/hooks/` | its hook scripts, copied from the package |
+| `~/.claude/settings.json` | one hook each for SessionStart, PostToolUse, Stop, SessionEnd — merged, a backup first |
+| `~/.claude/CLAUDE.md` | one line: `@~/.corkern/global/CLAUDE.md` |
+| `~/.claude/commands/corkern-*.md` | four slash commands |
+| `<project>/.claude/settings.local.json` | `autoMemoryDirectory` (kept out of the project's git) |
+
+What goes into `~/.claude` is the same on every machine (`$HOME`-relative, a no-op where corkern
+is not installed), so it works with dotfile managers such as yadm, chezmoi or stow. A file that is
+a symlink is never written through.
+
+## Status
+
+corkern was built by one developer for their own machines. Team use has only been simulated (10
+Docker containers, three teams, one untrusted intruder). Use it at your own risk; when something
+goes wrong, corkern reports it and keeps both versions rather than overwriting.
+
+Memories leave the machine only through git, to the knowledge repository you configure — and,
+when you run `corkern distill` or `corkern harvest`, to Claude for the analysis.
+
+For Claude Code there is an open request for built-in sync of user config and memory:
+[anthropics/claude-code#87027](https://github.com/anthropics/claude-code/issues/87027).
+
+## Licence
+
+MIT

corkern-2.0.0rc2/PYPI.md

@@ -0,0 +1,82 @@
+> ⚠ **First test release — please do not use it yet.**
+> This is corkern's first upload to PyPI, published only to try the release process. It is
+> not meant for use. A proper version is planned for the coming weeks.
+
+# corkern
+
+**Collective knowledge for Claude Code — across projects, devices and people.**
+
+Claude Code keeps what it learns about you and your work in per-project memory files on one
+machine. corkern turns that into a synced knowledge base: a private git repository that every
+machine you use reads from and writes to, so what was learned in one project, on one laptop, is
+there the next time — anywhere.
+
+## Install — once per machine
+
+```
+uv tool install corkern        # or: pipx install corkern
+corkern setup --clone git@github.com:<you>/<your-private-knowledge-repo>.git
+corkern signing                # this machine's signing (+ push) key — asks first
+corkern init-device --apply    # wire Claude Code — shows the plan, asks first
+corkern doctor                 # check the installation
+```
+
+First machine without a knowledge repo yet: `corkern setup --create-github <you>/<name>` creates
+it as a **private** GitHub repository (`--new` keeps it local).
+
+corkern is meant to be installed exactly once per user, as a tool. A copy inside a project's
+virtual environment refuses to act (only `--version`, `--help`, `doctor` and `status` run) —
+`corkern doctor` shows every copy it finds.
+
+## What it does
+
+- **Syncs memories** between machines through a private git repository you own: pulled when a
+  Claude session starts, committed as memories are written, pushed when Claude finishes a reply.
+- **Brings context into every session**: open reminders, recent session notes and important
+  memories are shown to Claude at session start.
+- **Keeps concurrent edits side by side**: when two machines change the same memory, both versions
+  are kept (`<name>.conflict-<host>-<time>.md`) and reported. Memory indexes and the project
+  registry merge line by line.
+- **Stays out of Claude's way**: the hooks always exit successfully; sync problems are recorded and
+  shown by `corkern status`.
+- **One key per machine**: each machine signs its memory commits with its own key and can push
+  with a deploy key limited to the knowledge repository.
+- **Accepts only what your devices signed** (opt-in, `corkern trust`): incoming memories signed by
+  any other key, or unsigned, are held back until you accept them.
+- **Keeps secrets out of the repository**: before every commit, known token formats, private keys
+  and `password = …`-style values are replaced by a marker; the original stays on that machine.
+  The scan is pattern-based: a secret in a format it does not know can still get through.
+- **Warns when `MEMORY.md` outgrows what Claude Code loads** (200 lines / 25 KB).
+- **Uses Claude Code's own setting** (`autoMemoryDirectory`) to point each project's memory at the
+  knowledge repository.
+
+## What corkern writes on your machine
+
+| File | What corkern adds |
+|---|---|
+| `~/.config/corkern/machine.conf` | this machine's knowledge repository (machine-local) |
+| `~/.local/share/corkern/hooks/` | its hook scripts, copied from the package |
+| `~/.claude/settings.json` | one hook each for SessionStart, PostToolUse, Stop, SessionEnd — merged, a backup first |
+| `~/.claude/CLAUDE.md` | one line: `@~/.corkern/global/CLAUDE.md` |
+| `~/.claude/commands/corkern-*.md` | four slash commands |
+| `<project>/.claude/settings.local.json` | `autoMemoryDirectory` (kept out of the project's git) |
+
+What goes into `~/.claude` is the same on every machine (`$HOME`-relative, a no-op where corkern
+is not installed), so it works with dotfile managers such as yadm, chezmoi or stow. A file that is
+a symlink is never written through.
+
+## Status
+
+corkern was built by one developer for their own machines. Team use has only been simulated (10
+Docker containers, three teams, one untrusted intruder). Use it at your own risk; when something
+goes wrong, corkern reports it and keeps both versions rather than overwriting.
+
+Memories leave the machine only through git, to the knowledge repository you configure — and,
+when you run `corkern distill` or `corkern harvest`, to Claude for the analysis.
+
+For Claude Code there is an open request for built-in sync of user config and memory:
+[anthropics/claude-code#87027](https://github.com/anthropics/claude-code/issues/87027).
+
+## Licence
+
+MIT

corkern-2.0.0rc2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "corkern"
+version = "2.0.0rc2"
+description = "Collective knowledge for Claude Code: syncs its memory across projects, devices and people through a private git repository"
+readme = "PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SCPG" }]
+requires-python = ">=3.10"
+keywords = ["claude", "claude-code", "memory", "sync", "git", "knowledge-base", "ai"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12,<1",
+    "rich>=13,<14",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3,<10",
+    "pytest-cov>=5,<6",
+]
+
+[project.scripts]
+corkern = "corkern.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/corkern"]
+
+# The source package holds the code, its licence and the PyPI page, nothing else — never tests, docs, docker, migrate or any
+# untracked folder (reports/, research_notes/, tmp.local/ may hold personal data). Enforced by
+# tests/test_package.py.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/corkern", "pyproject.toml", "PYPI.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

corkern-2.0.0rc2/src/corkern/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0rc2"

corkern-2.0.0rc2/src/corkern/claude_commands/corkern-distill.md

@@ -0,0 +1,12 @@
+Run `corkern distill` to synthesise cross-project insights from all corkern memory files.
+
+Steps:
+1. Ask the user whether to run interactively or auto-save:
+   - **Auto** (saves to `memory/global/synthesis.md`): run `corkern distill --auto`
+   - **Interactive** (review with Claude): run `corkern distill`
+2. Run the chosen command via Bash.
+3. If `--auto` was used, read `memory/global/synthesis.md` in the knowledge repo (`$CORKERN_MEMORY_DIR`) and summarise the findings to the user.
+4. For any **Stale Candidates** identified: offer to add `status: stale` to their frontmatter — one file at a time, with user confirmation for each.
+5. For any **Universal Principles** identified (rules appearing in 2+ projects): offer to add them to `memory/global/principles.md` and remove them from the individual project memory files — with user confirmation.
+
+Always confirm with the user before modifying any memory file.

corkern-2.0.0rc2/src/corkern/claude_commands/corkern-harvest.md

@@ -0,0 +1,13 @@
+Run `corkern harvest` to extract memories from past Claude conversations for the current project.
+
+Steps:
+1. Run `corkern prune` first to show which conversations are new, changed or already harvested.
+2. Run `corkern harvest` (detects the project from the current directory). With several conversations it asks which to process — answer `all` or numbers.
+3. Review the new memory files it lists in `memory/<slug>/` of the knowledge repo; they are already added to `MEMORY.md`. Existing files are never overwritten (a new version gets a `.harvested-<time>` suffix) — merge those with the user.
+4. If it saved a `harvested-<date>.md` bulk file instead, run `corkern refine`.
+
+Flags:
+- `corkern harvest --interactive` — opens an interactive Claude session with the conversations as context, so the user can add their own recollections.
+- `corkern harvest --all` — reprocesses already harvested conversations.
+
+Secrets in transcripts are replaced by a marker before anything is committed. After harvesting, run `/corkern-distill` to check whether any extracted memories should be promoted to global.

corkern-2.0.0rc2/src/corkern/claude_commands/corkern-memory-prune.md

@@ -0,0 +1,15 @@
+Run `corkern memory-prune` to archive expired or stale memory files for the current project.
+
+Steps:
+1. Run `corkern memory-prune --dry-run` to preview candidates without touching anything.
+2. Show the user the list of expired/stale files found.
+3. Explain what each candidate is and why it was flagged (expired date, status: stale marker).
+4. Ask the user to confirm before proceeding.
+5. If confirmed, run `corkern memory-prune` (which asks for confirmation again in the terminal).
+
+Notes:
+- Files with `expires: YYYY-MM-DD` in frontmatter are candidates after that date passes.
+- Files with `status: stale` in frontmatter are candidates regardless of date.
+- Archived files go to `memory/<slug>/archive/` — never deleted, always recoverable.
+- To mark a file stale: add `status: stale` inside its frontmatter `metadata:` block.
+- To mark a file with an expiry: add `expires: YYYY-MM-DD` inside `metadata:`.

corkern-2.0.0rc2/src/corkern/claude_commands/corkern-status.md

@@ -0,0 +1,6 @@
+Run `corkern status` to check corkern's health.
+
+- `corkern status` — summary: sync, signing and trust, secrets removed, memory index sizes, hooks, projects.
+- `corkern status -v` — full diagnostics: every project's wiring, hook scripts, slash commands, Claude Code memory folders not synced into corkern, knowledge graphs per project, IWE.
+
+Run this when something seems off with memory sync, or after setting up on a new machine. Report problems (✗) and warnings (!) to the user with the fix each line suggests.

corkern-2.0.0rc2/src/corkern/claude_print.py

@@ -0,0 +1,30 @@
+"""Text-in/text-out `claude -p` calls (distill --auto, harvest, refine).
+
+The prompt carries memory text that teammates wrote, so these calls get nothing beyond the
+text: no tools at all (`--tools ""`), only the user's own settings (`--setting-sources user`:
+no project or local settings, so no hooks from a repo), no MCP servers (`--strict-mcp-config`
+without `--mcp-config`), and they start in a fresh private empty folder instead of the
+knowledge repo (guard.capture_tool_isolated). Flags checked against Claude Code 2.1.285 and
+2.1.287 (`claude --help`).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from corkern import guard
+
+ISOLATION = ("--setting-sources", "user", "--strict-mcp-config", "--tools", "")
+
+
+def ask(claude: str, prompt: str, model: str | None = None) -> "guard.subprocess.CompletedProcess":
+    argv = [claude, "-p", *ISOLATION, *(["--model", model] if model else [])]
+    return guard.capture_tool_isolated(argv, prompt)
+
+
+def interactive_cwd(preferred: Path | None = None) -> Path:
+    """Where an interactive claude session starts: `preferred` (default: the current folder)
+    unless it is missing or inside the knowledge repo — then $HOME."""
+    where = Path(preferred) if preferred is not None else Path.cwd()
+    if not where.is_dir() or guard.in_knowledge_repo(where):
+        return Path.home()
+    return where

corkern-2.0.0rc2/src/corkern/commands/add_cmd.py

@@ -0,0 +1,104 @@
+import sys
+from pathlib import Path
+import typer
+from corkern import guard
+from corkern.commands.signing_cmd import _ask
+from corkern.config import (
+    UnstorablePath, _parse_conf, check_projects, confirm_projects, conf_entries, load_config,
+    resolve_project_path, same_path, store_project_path, valid_slug,
+)
+
+
+def _fail(message: str) -> None:
+    typer.echo(message, err=True)
+    raise typer.Exit(1)
+
+
+def add_project(
+    slug: str = typer.Argument(None, help="Project slug (default: the folder name, like v1)"),
+    path: Path = typer.Argument(None, help="Project path (default: cwd)"),
+    confirm_all: bool = typer.Option(False, "--confirm-all",
+                                     help="List every project not confirmed on this machine; confirm them after one question"),
+    confirm_listed: bool = typer.Option(False, "--confirm-listed",
+                                        help="Confirm the projects whose path matches the slug:path lines on stdin "
+                                             "(this machine's own v1 registry; used by migrate/3)"),
+) -> None:
+    """Add a project to tracking — or confirm on this machine a project that is already registered.
+
+    corkern.conf is shared: a project's path is used to read its Claude Code conversations
+    (harvest, prune) or to wire its folder (init-device) only once this machine confirmed it.
+    """
+    if confirm_all or confirm_listed:
+        _confirm_many(confirm_listed)
+        return
+    if slug is None:
+        slug = (path or Path(".")).resolve().name
+    if not valid_slug(slug):
+        _fail(f"Invalid slug {slug!r}: use letters, digits, '.', '_' or '-', "
+              "starting with a letter or digit.")
+    resolved = (path or Path(".")).resolve()
+    try:
+        stored = store_project_path(resolved)
+    except UnstorablePath as e:
+        _fail(f"Invalid path {str(resolved)!r}: {e}.")
+
+    repo, projects = load_config()
+    # Like v1: any line for the slug counts, including other devices' (e.g. Windows) lines
+    if slug in {s for s, _ in conf_entries(guard.read_text(repo.conf_file))}:
+        check = check_projects(repo.path).get(slug)
+        match = next((p for p in (check.candidates if check else ()) if same_path(p, resolved)), None)
+        if match is None:
+            _fail(f"Slug '{slug}' already exists. Remove it first.")
+        _confirm(repo.path, {slug: match})
+        typer.echo(f"Confirmed {slug} → {match} on this machine")
+        return
+    for other, other_path in projects.items():
+        if other_path.resolve() == resolved:
+            _fail(f"Path '{resolved}' is already tracked under slug '{other}'.")
+
+    _confirm(repo.path, {slug: resolve_project_path(stored)})
+    guard.append_text(repo.conf_file, f"{slug}:{stored}\n")
+    typer.echo(f"Added {slug} → {resolved}")
+
+
+def _confirm(repo: Path, items: dict[str, Path]) -> None:
+    try:
+        confirm_projects(repo, items)
+    except (OSError, guard.V1ProtectedError) as e:
+        _fail(f"Could not record the confirmation in {repo}/.git/corkern: {e}")
+
+
+def _confirm_many(listed: bool) -> None:
+    repo, _ = load_config()
+    open_ = [c for c in check_projects(repo.path).values() if not c.confirmed]
+    if listed:
+        theirs = _parse_conf(sys.stdin.read(), "stdin")
+        found: dict[str, Path] = {}
+        for c in open_:
+            if c.slug not in theirs:
+                continue
+            match = next((p for p in c.candidates if same_path(p, theirs[c.slug])), None)
+            if match is None:
+                typer.echo(f"  ! {c.slug}: the registry's path differs from the listed one "
+                           f"({', '.join(map(str, c.candidates))} ≠ {theirs[c.slug]}) — not confirmed")
+            else:
+                found[c.slug] = match
+        _confirm(repo.path, found)
+        for slug, p in sorted(found.items()):
+            typer.echo(f"  ✓ {slug} → {p} confirmed on this machine")
+        return
+    single = [c for c in open_ if not c.duplicate]
+    if not open_:
+        typer.echo("✓ Every project is confirmed on this machine.")
+        return
+    typer.echo("Not confirmed on this machine (corkern.conf is shared — check each path is yours):")
+    for c in single:
+        typer.echo(f"  {c.slug} → {c.candidates[0]}    ({c.lines[0]})")
+    for c in open_:
+        if c.duplicate:
+            typer.echo(f"  ! {c.explain()}")
+    if single and _ask(f"Confirm these {len(single)} project(s) on this machine? [y/N] ", False):
+        _confirm(repo.path, {c.slug: c.candidates[0] for c in single})
+        typer.echo(f"✓ {len(single)} project(s) confirmed")
+    elif single:
+        typer.echo("Nothing confirmed.")