claude-git-sessions 0.1.2 → 0.3.0

package/README.md

@@ -45,6 +45,8 @@ history with `main` and never contains your source files — only session data:
 ```
 sessions/<session-id>.jsonl        # the transcript, verbatim
 sessions/<session-id>.meta.json    # sidecar metadata (name, author, cwd, …)
+memory/<fact>.md                   # shared memory facts (see `ccgs memory`)
+memory/<fact>.md.meta.json         # sidecar metadata (type, author, …)
 ```
 
 Files are keyed by the globally-unique Claude Code session UUID, so transcripts
@@ -72,26 +74,32 @@ Branch names are validated with `git check-ref-format` before use.
 
 ## Commands
 
-### `ccgs pull`
+### `ccgs pull [--force] [--exclude-memory]`
 
-Fetches `@ccgs/<name>` and writes each session where Claude Code expects it:
-`~/.claude/projects/<local-slug>/<id>.jsonl`. The structural `cwd` field in each
-transcript line is rewritten from the author's path to your local equivalent so
-`claude --resume` works. (Absolute paths inside tool *output* are left as-is —
-cosmetic only.)
+Fetches `@ccgs/<name>` and writes each session into the **repo root's** project
+slug — `~/.claude/projects/<root-slug>/<id>.jsonl` — so that `claude --resume`
+run at the repo root lists every pulled session. The structural `cwd` field in
+each transcript line is rewritten from the author's path to your repo root so
+resume works. (Absolute paths inside tool *output* are left as-is — cosmetic.)
 
-If a local session is **newer** than the shared copy it is skipped with a
-warning; pass `--force` to overwrite anyway. Prints what was pulled / skipped.
+> Sessions are always placed under the repo-root slug, even if the author
+> launched Claude in a subdirectory. Honoring the author's subdir would put the
+> session in a separate (and possibly non-existent) slug dir where `--resume`
+> at the root can't see it. The original subdir is still recorded in `meta.json`.
 
-If the branch doesn't exist, it prints `nothing to pull` and exits 0.
+By default this **also pulls shared memory** (see `ccgs memory`); pass
+`--exclude-memory` for sessions only. If a local session is **newer** than the
+shared copy it is skipped with a warning; pass `--force` to overwrite. If the
+branch doesn't exist, it prints `nothing to pull` and exits 0.
 
-### `ccgs push [targets...]`
+### `ccgs push [targets...] [--exclude-memory]`
 
 Finds local sessions whose working directory is this repo (or a subdirectory),
 copies each transcript verbatim onto the orphan branch, and (re)generates its
 `meta.json`. With no arguments it pushes all of them; pass session ids/names to
-push only those. Creates the orphan branch on first push. Reports added vs
-updated.
+push only those. By default this **also pushes shared memory** (project /
+reference facts); pass `--exclude-memory` for sessions only. Creates the orphan
+branch on first push. Reports added vs updated.
 
 ### `ccgs delete <id|name> [--yes] [--local]`
 
@@ -101,6 +109,33 @@ Shows what will be deleted and asks for `y/N` confirmation (`--yes`/`-y` to skip
 for scripting). Removes both files from the branch and pushes. By default only
 the shared branch is touched; add `--local` to also remove the local copy.
 
+### `ccgs memory push [--all]` / `ccgs memory pull [--all] [--force]`
+
+Claude Code keeps per-project memory in `~/.claude/projects/<slug>/memory/` —
+one Markdown file per fact, plus a `MEMORY.md` index. `ccgs memory` shares those
+facts on the same orphan branch (under a `memory/` prefix).
+
+Plain `ccgs push` / `ccgs pull` already include memory by default (with the
+type filter below, i.e. no personal facts). Use these `memory` subcommands when
+you want memory **only**, or need `--all` to include personal facts.
+
+Memory is *mixed-sensitivity*, so it's filtered by the fact's frontmatter
+`type`:
+
+- **`project` / `reference`** facts ("how we deploy", "where the API docs live")
+  are team knowledge and are shared **by default**.
+- **`user` / `feedback`** facts (personal preferences) are held back unless you
+  pass **`--all`**.
+
+`pull` writes the shared facts into your local memory dir and maintains a
+clearly-marked block inside your `MEMORY.md` pointing at them — **your own index
+lines are left untouched**. `MEMORY.md` itself is never pushed as a blob (two
+people's indexes would clobber each other). Facts are keyed by filename with
+newer-wins conflict handling (`--force` to overwrite a newer local copy).
+
+> Scope: only the repo **root** slug's memory dir is synced (the common case);
+> memory from sessions started in subdirectories is not.
+
 ### Global options
 
 | Option | Default | Meaning |

package/dist/commands/memory.js

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { MEMORY_DIR, MEMORY_INDEX } from "../constants.js";
+import { applyToOrphanBranch, assertRemote, fetchBranch, localTrackingRef, lsTreeUnder, showFile, validateBranchName, } from "../git.js";
+import { gitAuthor } from "../meta.js";
+import { indexLine, isShareable, memoryDir, parseFrontmatter, readLocalMemory, titleFor, updateIndexBlock, } from "../memory.js";
+function metaPath(filename) {
+    return `${MEMORY_DIR}/${filename}.meta.json`;
+}
+function blobPath(filename) {
+    return `${MEMORY_DIR}/${filename}`;
+}
+/** Filenames of `.md` memory facts on the branch (excludes sidecars). */
+async function listBranchMemory(repo, ref) {
+    const paths = await lsTreeUnder(repo, ref, MEMORY_DIR);
+    const names = new Set();
+    for (const p of paths) {
+        const m = p.match(new RegExp(`^${MEMORY_DIR}/(.+\\.md)$`));
+        if (m && m[1] !== MEMORY_INDEX)
+            names.add(m[1]);
+    }
+    return [...names];
+}
+export async function memoryPush(opts) {
+    await validateBranchName(opts.repoRoot, opts.branch);
+    await assertRemote(opts.repoRoot, opts.remote);
+    const all = readLocalMemory(opts.repoRoot);
+    const shareable = all.filter((f) => isShareable(f.type, opts.all));
+    const heldBack = all.length - shareable.length;
+    if (shareable.length === 0) {
+        const extra = heldBack
+            ? ` (${heldBack} personal user/feedback memo(ies) held back; use --all to include)`
+            : "";
+        console.log(`nothing to push (no shareable memory found for this repo)${extra}`);
+        return 0;
+    }
+    await fetchBranch(opts.repoRoot, opts.remote, opts.branch);
+    const ref = localTrackingRef(opts.branch);
+    const existing = new Set(await listBranchMemory(opts.repoRoot, ref).catch(() => []));
+    const author = await gitAuthor(opts.repoRoot);
+    const added = [];
+    const updated = [];
+    let unchanged = 0;
+    for (const f of shareable) {
+        if (!existing.has(f.filename)) {
+            added.push(f.filename);
+        }
+        else {
+            const prev = await showFile(opts.repoRoot, ref, blobPath(f.filename));
+            if (prev === f.content)
+                unchanged++;
+            else
+                updated.push(f.filename);
+        }
+    }
+    const result = await applyToOrphanBranch(opts.repoRoot, opts.remote, opts.branch, `ccgs: push ${added.length + updated.length} memory file(s)`, async (b) => {
+        for (const f of shareable) {
+            const sidecar = {
+                filename: f.filename,
+                type: f.type,
+                name: f.name,
+                description: f.description,
+                author,
+                machine: os.hostname(),
+                updatedAt: f.updatedAt,
+            };
+            await b.addBlob(blobPath(f.filename), f.content);
+            await b.addBlob(metaPath(f.filename), JSON.stringify(sidecar, null, 2) + "\n");
+        }
+    });
+    if (!result.changed) {
+        console.log(`Memory already up to date — ${unchanged} file(s) unchanged.`);
+        if (heldBack)
+            console.log(`(${heldBack} personal memo(ies) held back; --all to include)`);
+        return 0;
+    }
+    if (added.length) {
+        console.log(`Added ${added.length}:`);
+        for (const a of added)
+            console.log(`  + ${a}`);
+    }
+    if (updated.length) {
+        console.log(`Updated ${updated.length}:`);
+        for (const u of updated)
+            console.log(`  ~ ${u}`);
+    }
+    if (unchanged)
+        console.log(`(${unchanged} unchanged)`);
+    if (heldBack)
+        console.log(`(${heldBack} personal user/feedback memo(ies) held back; --all to include)`);
+    console.log(`Pushed memory to ${opts.remote} @ccgs/${opts.branch}.`);
+    return 0;
+}
+export async function memoryPull(opts) {
+    await validateBranchName(opts.repoRoot, opts.branch);
+    await assertRemote(opts.repoRoot, opts.remote);
+    const exists = await fetchBranch(opts.repoRoot, opts.remote, opts.branch);
+    if (!exists) {
+        console.log("nothing to pull (branch does not exist on remote)");
+        return 0;
+    }
+    const ref = localTrackingRef(opts.branch);
+    const filenames = await listBranchMemory(opts.repoRoot, ref);
+    if (filenames.length === 0) {
+        console.log("nothing to pull (no shared memory on branch)");
+        return 0;
+    }
+    const dir = memoryDir(opts.repoRoot);
+    const pulled = [];
+    const skipped = [];
+    // Files present locally after this pull, for index regeneration.
+    const indexEntries = [];
+    for (const filename of filenames) {
+        const content = await showFile(opts.repoRoot, ref, blobPath(filename));
+        if (content === null) {
+            skipped.push(`${filename}: missing blob`);
+            continue;
+        }
+        const rawMeta = await showFile(opts.repoRoot, ref, metaPath(filename));
+        let sidecar = null;
+        if (rawMeta) {
+            try {
+                sidecar = JSON.parse(rawMeta);
+            }
+            catch {
+                sidecar = null;
+            }
+        }
+        const type = sidecar?.type ?? parseFrontmatter(content).type;
+        // Apply the same type gate on pull: don't litter local memory with other
+        // people's personal facts unless explicitly asked.
+        if (!isShareable(type, opts.all)) {
+            continue;
+        }
+        const description = sidecar?.description ?? parseFrontmatter(content).description;
+        const localFile = path.join(dir, filename);
+        // Conflict policy: keep a newer local copy unless --force.
+        if (!opts.force && fs.existsSync(localFile)) {
+            const branchUpdated = sidecar?.updatedAt ?? "";
+            const localUpdated = fs.statSync(localFile).mtime.toISOString();
+            if (branchUpdated && localUpdated > branchUpdated) {
+                skipped.push(`${filename}: local copy is newer (use --force)`);
+                // Still index it — the file exists locally and is part of the shared set.
+                indexEntries.push({ filename, description, title: titleFor({ filename, name: sidecar?.name ?? null }) });
+                continue;
+            }
+        }
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(localFile, content);
+        pulled.push(filename);
+        indexEntries.push({ filename, description, title: titleFor({ filename, name: sidecar?.name ?? null }) });
+    }
+    // Rebuild the ccgs-managed block in MEMORY.md from the shared set.
+    if (indexEntries.length) {
+        const indexPath = path.join(dir, MEMORY_INDEX);
+        let existing = "";
+        try {
+            existing = fs.readFileSync(indexPath, "utf8");
+        }
+        catch {
+            existing = "";
+        }
+        const lines = indexEntries
+            .sort((a, b) => a.filename.localeCompare(b.filename))
+            .map((e) => indexLine(e));
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(indexPath, updateIndexBlock(existing, lines));
+    }
+    if (pulled.length) {
+        console.log(`Pulled ${pulled.length} memory file(s):`);
+        for (const p of pulled)
+            console.log(`  + ${p}`);
+        console.log(`Index updated: ${path.join(dir, MEMORY_INDEX)}`);
+    }
+    else {
+        console.log("Pulled 0 memory files.");
+    }
+    if (skipped.length) {
+        console.log(`Skipped ${skipped.length}:`);
+        for (const s of skipped)
+            console.log(`  - ${s}`);
+    }
+    return 0;
+}

package/dist/commands/pull.js

@@ -1,5 +1,4 @@
 import fs from "node:fs";
-import path from "node:path";
 import { SESSIONS_DIR } from "../constants.js";
 import { assertRemote, fetchBranch, localTrackingRef, showFile, validateBranchName, } from "../git.js";
 import { listBranchSessions } from "../branch-sessions.js";
@@ -28,9 +27,13 @@ export async function pull(opts) {
             skipped.push(`${shortId(id)}: missing transcript blob`);
             continue;
         }
-        // Reconstruct the local cwd for this session: repo root + recorded subdir.
-        const rel = meta?.cwdRelativeToRepoRoot ?? "";
-        const localCwd = rel ? path.join(opts.repoRoot, rel) : opts.repoRoot;
+        // Always land the session under the repo ROOT slug, so `claude --resume`
+        // run at the repo root lists it. (We deliberately do NOT honor the author's
+        // `cwdRelativeToRepoRoot` here: that placed subdir-authored sessions in a
+        // separate — and often non-existent — slug dir, making them invisible to
+        // resume at the root. The author's subdir is still recorded in meta for
+        // provenance.)
+        const localCwd = opts.repoRoot;
         const name = meta?.name ?? id;
         // Conflict policy: newer local copy is kept unless --force.
         const localFile = sessionFilePath(localCwd, id);

package/dist/constants.js

@@ -15,5 +15,12 @@ export const DEFAULT_BRANCH_NAME = "default";
 export const DEFAULT_REMOTE = "origin";
 /** Path prefix used for session blobs on the orphan branch. */
 export const SESSIONS_DIR = "sessions";
+/**
+ * Path prefix used for shared memory blobs on the orphan branch, and the name
+ * of the local memory subdirectory inside a project's slug dir.
+ */
+export const MEMORY_DIR = "memory";
+/** The hand-maintained memory index file (lives inside the memory dir). */
+export const MEMORY_INDEX = "MEMORY.md";
 /** Max length of an auto-derived display name. */
 export const DISPLAY_NAME_MAX = 80;

package/dist/git.js

@@ -115,15 +115,19 @@ export async function trackingTip(repo, name) {
     const sha = r.stdout.trim();
     return sha || null;
 }
-/** List `sessions/*` paths present on a tree-ish ref. */
-export async function lsSessions(repo, ref) {
+/** List paths under `prefix/` present on a tree-ish ref. */
+export async function lsTreeUnder(repo, ref, prefix) {
     const r = await git(["ls-tree", "-r", "--name-only", ref], { cwd: repo, allowFail: true });
     if (r.code !== 0)
         return [];
     return r.stdout
         .split("\n")
         .map((s) => s.trim())
-        .filter((p) => p.startsWith(`${SESSIONS_DIR}/`));
+        .filter((p) => p.startsWith(`${prefix}/`));
+}
+/** List `sessions/*` paths present on a tree-ish ref. */
+export async function lsSessions(repo, ref) {
+    return lsTreeUnder(repo, ref, SESSIONS_DIR);
 }
 /** Read a blob at `ref:path` as utf-8 text, or null if it does not exist. */
 export async function showFile(repo, ref, filePath) {

package/dist/index.js

@@ -5,9 +5,10 @@ import { repoRoot } from "./git.js";
 import { pull } from "./commands/pull.js";
 import { push } from "./commands/push.js";
 import { deleteSession } from "./commands/delete.js";
+import { memoryPull, memoryPush } from "./commands/memory.js";
 // Kept in sync with package.json at publish time; hardcoded to avoid a JSON
 // import assertion just for --version.
-const VERSION = "0.1.2";
+const VERSION = "0.3.0";
 function globals(cmd) {
     const opts = cmd.optsWithGlobals();
     return {
@@ -33,24 +34,44 @@ program
     .option("--remote <remote>", "git remote to use", DEFAULT_REMOTE);
 program
     .command("pull")
-    .description("fetch shared sessions and place them where Claude Code can resume them")
+    .description("fetch shared sessions (and memory) and place them where Claude Code can resume them")
     .option("--force", "overwrite local copies even if they are newer", false)
+    .option("--exclude-memory", "pull sessions only; do not also pull memory", false)
     .action(async (localOpts, cmd) => {
     const g = globals(cmd);
     await run(async () => {
         const root = await repoRoot();
-        return pull({ repoRoot: root, remote: g.remote, branch: g.branch, force: localOpts.force });
+        let code = await pull({ repoRoot: root, remote: g.remote, branch: g.branch, force: localOpts.force });
+        if (!localOpts.excludeMemory) {
+            console.log("\nMemory:");
+            const m = await memoryPull({
+                repoRoot: root,
+                remote: g.remote,
+                branch: g.branch,
+                all: false,
+                force: localOpts.force,
+            });
+            code = code || m;
+        }
+        return code;
     });
 });
 program
     .command("push")
-    .description("publish this repo's local sessions to the orphan branch")
+    .description("publish this repo's local sessions (and shared memory) to the orphan branch")
     .argument("[targets...]", "optional session ids/names to push (default: all)")
-    .action(async (targets, _localOpts, cmd) => {
+    .option("--exclude-memory", "push sessions only; do not also push memory", false)
+    .action(async (targets, localOpts, cmd) => {
     const g = globals(cmd);
     await run(async () => {
         const root = await repoRoot();
-        return push({ repoRoot: root, remote: g.remote, branch: g.branch, filters: targets });
+        let code = await push({ repoRoot: root, remote: g.remote, branch: g.branch, filters: targets });
+        if (!localOpts.excludeMemory) {
+            console.log("\nMemory:");
+            const m = await memoryPush({ repoRoot: root, remote: g.remote, branch: g.branch, all: false });
+            code = code || m;
+        }
+        return code;
     });
 });
 program
@@ -73,6 +94,43 @@ program
         });
     });
 });
+const memory = program
+    .command("memory")
+    .description("share Claude Code memory files (project/reference facts) for this repo");
+memory
+    .command("push")
+    .description("publish this repo's shareable memory to the orphan branch")
+    .option("--all", "include personal user/feedback memories too", false)
+    .action(async (localOpts, cmd) => {
+    const g = globals(cmd);
+    await run(async () => {
+        const root = await repoRoot();
+        return memoryPush({ repoRoot: root, remote: g.remote, branch: g.branch, all: localOpts.all });
+    });
+});
+memory
+    .command("pull")
+    .description("fetch shared memory and update this repo's local MEMORY.md index")
+    .option("--all", "include personal user/feedback memories too", false)
+    .option("--force", "overwrite local copies even if they are newer", false)
+    .action(async (localOpts, cmd) => {
+    const g = globals(cmd);
+    await run(async () => {
+        const root = await repoRoot();
+        return memoryPull({
+            repoRoot: root,
+            remote: g.remote,
+            branch: g.branch,
+            all: localOpts.all,
+            force: localOpts.force,
+        });
+    });
+});
+// `ccgs memory` with no subcommand: show its help on stdout and exit 0.
+memory.action(() => {
+    memory.outputHelp();
+    process.exit(0);
+});
 // With no subcommand, print help to stdout and exit 0 — Commander's default is
 // to print to stderr and exit 1, which looks like an error to anyone running
 // the bare command (e.g. `npx claude-git-sessions`).

package/dist/memory.js

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MEMORY_DIR, MEMORY_INDEX } from "./constants.js";
+import { projectDirForCwd } from "./paths.js";
+const KNOWN_TYPES = ["user", "feedback", "project", "reference"];
+/** Local memory directory for the repo's root slug. */
+export function memoryDir(repoRoot) {
+    return path.join(projectDirForCwd(repoRoot), MEMORY_DIR);
+}
+function stripQuotes(s) {
+    const t = s.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+/**
+ * Minimal frontmatter reader for the known memory format. Deliberately not a
+ * full YAML parser — it only pulls out `name`, `description`, and the nested
+ * `type`, and degrades gracefully (type "unknown") on anything unexpected.
+ */
+export function parseFrontmatter(content) {
+    let name = null;
+    let description = null;
+    let type = "unknown";
+    if (content.startsWith("---")) {
+        // Find the closing delimiter line.
+        const rest = content.slice(3);
+        const endIdx = rest.search(/\n---\s*(\n|$)/);
+        if (endIdx !== -1) {
+            const block = rest.slice(0, endIdx);
+            for (const line of block.split("\n")) {
+                const n = line.match(/^\s*name:\s*(.+?)\s*$/);
+                if (n && name === null)
+                    name = stripQuotes(n[1]);
+                const d = line.match(/^\s*description:\s*(.+?)\s*$/);
+                if (d && description === null)
+                    description = stripQuotes(d[1]);
+                const t = line.match(/^\s*type:\s*([A-Za-z]+)/);
+                if (t) {
+                    const v = t[1].toLowerCase();
+                    if (KNOWN_TYPES.includes(v))
+                        type = v;
+                }
+            }
+        }
+    }
+    return { name, description, type };
+}
+/** Should a fact of `type` be shared? `all` overrides the type filter. */
+export function isShareable(type, all) {
+    if (all)
+        return true;
+    return type === "project" || type === "reference";
+}
+/** kebab-or-filename -> a human "Title Case" string for the index link text. */
+export function titleFor(file) {
+    const base = file.name ?? file.filename.replace(/\.md$/i, "");
+    return base
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** Read all shareable-candidate memory files from the repo's memory dir. */
+export function readLocalMemory(repoRoot) {
+    const dir = memoryDir(repoRoot);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const filename of entries) {
+        if (!filename.endsWith(".md"))
+            continue;
+        if (filename === MEMORY_INDEX)
+            continue; // index handled separately
+        const p = path.join(dir, filename);
+        let content;
+        let mtime;
+        try {
+            const st = fs.statSync(p);
+            if (!st.isFile())
+                continue;
+            mtime = st.mtime;
+            content = fs.readFileSync(p, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const fm = parseFrontmatter(content);
+        out.push({
+            filename,
+            path: p,
+            content,
+            name: fm.name,
+            description: fm.description,
+            type: fm.type,
+            updatedAt: mtime.toISOString(),
+        });
+    }
+    return out;
+}
+const BLOCK_START = "<!-- ccgs:shared-memory (managed by ccgs; do not edit by hand) -->";
+const BLOCK_END = "<!-- /ccgs:shared-memory -->";
+/** One index pointer line: `- [Title](file.md) — description`. */
+export function indexLine(file) {
+    const tail = file.description ? ` — ${file.description}` : "";
+    return `- [${file.title}](${file.filename})${tail}`;
+}
+/**
+ * Replace (or append) the ccgs-managed block in a MEMORY.md body with the given
+ * lines, leaving everything outside the markers untouched. Returns the new body.
+ */
+export function updateIndexBlock(existing, lines) {
+    const block = lines.length
+        ? `${BLOCK_START}\n${lines.join("\n")}\n${BLOCK_END}`
+        : `${BLOCK_START}\n${BLOCK_END}`;
+    const startIdx = existing.indexOf(BLOCK_START);
+    const endIdx = existing.indexOf(BLOCK_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + BLOCK_END.length);
+        return before + block + after;
+    }
+    // Append, ensuring a blank line separates it from existing content.
+    const base = existing.trimEnd();
+    if (base === "")
+        return block + "\n";
+    return `${base}\n\n${block}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-git-sessions",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Share Claude Code sessions across a team through an orphan git branch in your existing repo.",
   "keywords": ["claude", "claude-code", "git", "sessions", "cli"],
   "license": "MIT",