claude-code-swarm 0.3.7 → 0.3.8

package/references/agent-inbox/test/wake.test.ts

@@ -1,330 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { EventEmitter } from "node:events";
-import { InMemoryStorage } from "../src/storage/memory.js";
-import { MessageRouter } from "../src/router/message-router.js";
-import { PushNotifier } from "../src/push/notifier.js";
-import type { InboxMessageEvent } from "../src/push/notifier.js";
-import { WarmRegistry } from "../src/registry/warm-registry.js";
-import { parseCommand } from "../src/push/notifier.js";
-import type { Agent } from "../src/types.js";
-
-function makeAgent(id: string, scope = "default"): Agent {
-  const now = new Date().toISOString();
-  return {
-    agent_id: id,
-    display_name: id,
-    scope,
-    status: "active",
-    metadata: {},
-    registered_at: now,
-    last_active_at: now,
-  };
-}
-
-describe("WarmRegistry dormant state", () => {
-  let storage: InMemoryStorage;
-  let events: EventEmitter;
-  let registry: WarmRegistry;
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-    storage = new InMemoryStorage();
-    events = new EventEmitter();
-    registry = new WarmRegistry(storage, events, {
-      gracePeriodMs: 5000,
-      retainExpiredMs: 10000,
-      requeueOnReconnect: true,
-    });
-  });
-
-  afterEach(() => {
-    registry.destroy();
-    vi.useRealTimers();
-  });
-
-  it("should transition active agent to dormant", () => {
-    registry.register(makeAgent("agent-1"));
-    const ok = registry.dormant("agent-1");
-    expect(ok).toBe(true);
-    expect(registry.getStatus("agent-1")).toBe("dormant");
-    expect(registry.isRoutable("agent-1")).toBe(false);
-  });
-
-  it("should transition away agent to dormant", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.disconnect("agent-1");
-    const ok = registry.dormant("agent-1");
-    expect(ok).toBe(true);
-    expect(registry.getStatus("agent-1")).toBe("dormant");
-  });
-
-  it("should not transition expired agent to dormant", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.disconnect("agent-1");
-    vi.advanceTimersByTime(6000);
-    expect(registry.getStatus("agent-1")).toBe("expired");
-    const ok = registry.dormant("agent-1");
-    expect(ok).toBe(false);
-  });
-
-  it("should wake a dormant agent back to active", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    const ok = registry.wake("agent-1");
-    expect(ok).toBe(true);
-    expect(registry.getStatus("agent-1")).toBe("active");
-    expect(registry.isRoutable("agent-1")).toBe(true);
-  });
-
-  it("should not wake a non-dormant agent", () => {
-    registry.register(makeAgent("agent-1"));
-    expect(registry.wake("agent-1")).toBe(false); // active, not dormant
-  });
-
-  it("should emit registry.dormant event", () => {
-    const spy = vi.fn();
-    events.on("registry.dormant", spy);
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    expect(spy).toHaveBeenCalledWith("agent-1");
-  });
-
-  it("should emit registry.woken event", () => {
-    const spy = vi.fn();
-    events.on("registry.woken", spy);
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    registry.wake("agent-1");
-    expect(spy).toHaveBeenCalledWith("agent-1");
-  });
-
-  it("should update storage status to offline when dormant", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    const stored = storage.getAgent("agent-1");
-    expect(stored?.status).toBe("offline");
-  });
-
-  it("should update storage status to active when woken", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    registry.wake("agent-1");
-    const stored = storage.getAgent("agent-1");
-    expect(stored?.status).toBe("active");
-  });
-
-  it("should allow re-registering a dormant agent", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    const ok = registry.register(makeAgent("agent-1"));
-    expect(ok).toBe(true);
-    expect(registry.getStatus("agent-1")).toBe("active");
-  });
-
-  it("should list dormant agents in listEntries", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.register(makeAgent("agent-2"));
-    registry.dormant("agent-1");
-    const entries = registry.listEntries();
-    const dormant = entries.find((e) => e.agentId === "agent-1");
-    expect(dormant?.warmStatus).toBe("dormant");
-  });
-
-  it("should not list dormant agents in listRoutable", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.dormant("agent-1");
-    expect(registry.listRoutable()).not.toContain("agent-1");
-  });
-
-  it("should clear grace timer when going dormant from away", () => {
-    registry.register(makeAgent("agent-1"));
-    registry.disconnect("agent-1");
-    registry.dormant("agent-1");
-    // Advancing past grace period should NOT transition to expired
-    vi.advanceTimersByTime(6000);
-    expect(registry.getStatus("agent-1")).toBe("dormant");
-  });
-});
-
-describe("PushNotifier inbox.message events", () => {
-  let storage: InMemoryStorage;
-  let events: EventEmitter;
-  let router: MessageRouter;
-  let notifier: PushNotifier;
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "inbox-wake-test-"));
-    storage = new InMemoryStorage();
-    events = new EventEmitter();
-    router = new MessageRouter(storage, events, "default");
-    notifier = new PushNotifier({ inboxDir: tmpDir }, storage, events);
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("should emit inbox.message event per recipient", async () => {
-    const spy = vi.fn();
-    events.on("inbox.message", spy);
-
-    await router.routeMessage({
-      from: "alice",
-      to: "bob",
-      payload: "hello",
-    });
-
-    expect(spy).toHaveBeenCalledTimes(1);
-    expect(spy).toHaveBeenCalledWith(
-      expect.objectContaining({
-        agentId: "bob",
-        recipientKind: "to",
-        message: expect.objectContaining({
-          sender_id: "alice",
-        }),
-      })
-    );
-  });
-
-  it("should emit one event per recipient for multi-recipient messages", async () => {
-    const spy = vi.fn();
-    events.on("inbox.message", spy);
-
-    await router.routeMessage({
-      from: "alice",
-      to: [
-        { agent_id: "bob", kind: "to" },
-        { agent_id: "carol", kind: "cc" },
-      ],
-      payload: "hello team",
-    });
-
-    expect(spy).toHaveBeenCalledTimes(2);
-
-    const calls = spy.mock.calls.map((c: [InboxMessageEvent]) => ({
-      agentId: c[0].agentId,
-      kind: c[0].recipientKind,
-    }));
-    expect(calls).toContainEqual({ agentId: "bob", kind: "to" });
-    expect(calls).toContainEqual({ agentId: "carol", kind: "cc" });
-  });
-
-  it("should include full message in event", async () => {
-    const spy = vi.fn();
-    events.on("inbox.message", spy);
-
-    await router.routeMessage({
-      from: "alice",
-      to: "bob",
-      payload: "urgent fix needed",
-      importance: "high",
-      threadTag: "critical-bug",
-      subject: "Production down",
-    });
-
-    const event: InboxMessageEvent = spy.mock.calls[0][0];
-    expect(event.message.importance).toBe("high");
-    expect(event.message.thread_tag).toBe("critical-bug");
-    expect(event.message.subject).toBe("Production down");
-  });
-
-  it("should write inbox file for each recipient", async () => {
-    await router.routeMessage({
-      from: "alice",
-      to: "bob",
-      payload: "wake up!",
-    });
-
-    const filePath = notifier.agentInboxPath("bob");
-    expect(fs.existsSync(filePath)).toBe(true);
-    const raw = fs.readFileSync(filePath, "utf-8").trim();
-    expect(raw).toContain("alice");
-  });
-
-  it("should allow clients to implement their own filtering", async () => {
-    // Simulate a client that only cares about high/urgent messages
-    const wokenAgents: string[] = [];
-
-    events.on("inbox.message", (event: InboxMessageEvent) => {
-      if (["high", "urgent"].includes(event.message.importance)) {
-        wokenAgents.push(event.agentId);
-      }
-    });
-
-    // Normal importance — client ignores
-    await router.routeMessage({
-      from: "alice",
-      to: "bob",
-      payload: "low priority",
-      importance: "normal",
-    });
-    expect(wokenAgents).toHaveLength(0);
-
-    // High importance — client acts
-    await router.routeMessage({
-      from: "alice",
-      to: "bob",
-      payload: "urgent fix needed",
-      importance: "high",
-    });
-    expect(wokenAgents).toEqual(["bob"]);
-  });
-
-  it("should allow clients to implement cooldown logic", async () => {
-    const wokenAgents: string[] = [];
-    const lastWake = new Map<string, number>();
-    const cooldownMs = 10_000;
-
-    vi.useFakeTimers();
-
-    events.on("inbox.message", (event: InboxMessageEvent) => {
-      const last = lastWake.get(event.agentId) ?? 0;
-      if (Date.now() - last >= cooldownMs) {
-        lastWake.set(event.agentId, Date.now());
-        wokenAgents.push(event.agentId);
-      }
-    });
-
-    // First message — wakes
-    await router.routeMessage({ from: "alice", to: "bob", payload: "msg 1" });
-    expect(wokenAgents).toHaveLength(1);
-
-    // Second within cooldown — skipped
-    await router.routeMessage({ from: "alice", to: "bob", payload: "msg 2" });
-    expect(wokenAgents).toHaveLength(1);
-
-    // After cooldown — wakes again
-    vi.advanceTimersByTime(10_001);
-    await router.routeMessage({ from: "alice", to: "bob", payload: "msg 3" });
-    expect(wokenAgents).toHaveLength(2);
-
-    vi.useRealTimers();
-  });
-});
-
-describe("parseCommand", () => {
-  it("should split simple commands", () => {
-    expect(parseCommand("echo hello world")).toEqual(["echo", "hello", "world"]);
-  });
-
-  it("should handle quoted strings", () => {
-    expect(parseCommand('echo "hello world"')).toEqual(["echo", "hello world"]);
-  });
-
-  it("should handle single-quoted strings", () => {
-    expect(parseCommand("echo 'hello world'")).toEqual(["echo", "hello world"]);
-  });
-
-  it("should handle empty input", () => {
-    expect(parseCommand("")).toEqual([]);
-  });
-
-  it("should handle template variables", () => {
-    const cmd = "claude --resume session-123";
-    expect(parseCommand(cmd)).toEqual(["claude", "--resume", "session-123"]);
-  });
-});

package/references/agent-inbox/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist", "test"]
-}

package/references/agent-inbox/tsup.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts"],
-  format: ["cjs", "esm"],
-  dts: true,
-  splitting: false,
-  sourcemap: true,
-  clean: true,
-});

package/references/agent-inbox/vitest.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    include: ["test/**/*.test.ts"],
-    testTimeout: 10_000,
-  },
-});

package/references/minimem/.claude/settings.json

@@ -1,7 +0,0 @@
-{
-    "attribution": 
-    {
-        "commit": "",
-        "pr": ""
-    }
-}

package/references/minimem/.sudocode/issues.jsonl

@@ -1,18 +0,0 @@
-{"id":"i-7edu","uuid":"d7e8cb3b-73c5-4ac8-b0c3-75d30b3af857","title":"Implement global and per-directory config system for sync","content":"## Overview\nExtend the existing config system to support sync-related configuration at both global and per-directory levels.\n\n## Acceptance Criteria\n- [ ] Global config at `~/.config/minimem/config.json` supports:\n  - `centralRepo`: path to central repository\n  - `sync.conflictStrategy`: default merge strategy\n  - `sync.autoSync`: boolean for daemon auto-sync\n  - `sync.autoCommit`: boolean for auto-committing\n- [ ] Per-directory config at `.minimem/config.json` supports:\n  - `sync.enabled`: boolean\n  - `sync.path`: path in central repo\n  - `sync.include`: glob patterns for files to sync\n  - `sync.exclude`: glob patterns to exclude\n- [ ] Default include pattern: `[\"MEMORY.md\", \"memory/**/*.md\"]`\n- [ ] Config loading merges global defaults with per-directory overrides\n- [ ] `minimem config set` and `minimem config get` work for sync settings\n\n## Technical Notes\n- Extend existing `src/cli/config.ts`\n- Use JSON schema validation for config\n- Handle `~` expansion in paths\n\n## Implements\n[[s-2wx5]] - Config system requirement","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:55:58","updated_at":"2026-02-03 05:36:54","closed_at":"2026-02-03 05:36:54","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7edu","from_type":"issue","to":"i-1ce6","to_type":"issue","type":"blocks"},{"from":"i-7edu","from_type":"issue","to":"i-1tlk","to_type":"issue","type":"blocks"},{"from":"i-7edu","from_type":"issue","to":"i-8gam","to_type":"issue","type":"blocks"},{"from":"i-7edu","from_type":"issue","to":"i-dvoe","to_type":"issue","type":"blocks"},{"from":"i-7edu","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","config","foundation"],"feedback":[{"id":"a8f202b4-f0a8-4455-816d-78bbb53e06f5","from_id":"i-7edu","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented config system for sync with:\n- Extended CliConfig with sync section (enabled, path, include, exclude)\n- Added GlobalConfig type for XDG config (~/.config/minimem/config.json)\n- Added centralRepo, machineId, and sync settings to global config\n- Added expandPath utility for ~ expansion\n- Added loadXdgConfig, saveXdgConfig functions\n- Added getMachineId function (generates hostname-{random4hex})\n- Added getSyncConfig to merge local + global with defaults\n- Updated config command to display sync settings\n- Added --xdg-global flag to config command\n- All 39 tests pass","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T05:36:54.045Z","updated_at":"2026-02-03T05:36:54.045Z"}]}
-{"id":"i-1tlk","uuid":"855b8770-3183-4956-8b80-d9b7b26b173f","title":"Implement directory type auto-detection","content":"## Overview\nDetect which of the four directory types a memory directory is: project-bound, standalone, hybrid, or unmanaged.\n\n## Acceptance Criteria\n- [ ] `detectDirectoryType(dir: string)` function returns one of:\n  - `project-bound`: inside git repo, no sync config\n  - `standalone`: has sync config, not inside git repo\n  - `hybrid`: inside git repo AND has sync config\n  - `unmanaged`: no git repo, no sync config\n- [ ] Detection checks for `.git` in parent directories\n- [ ] Detection reads `.minimem/config.json` for sync config\n- [ ] Exported for use by other commands (sync, push, pull, daemon)\n- [ ] Unit tests for all four detection cases\n\n## Technical Notes\n- Walk up directory tree looking for `.git`\n- Check for `sync.enabled` in local config\n- Consider caching result per session\n\n## Implements\n[[s-2wx5]] - Auto-detection requirement","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:06","updated_at":"2026-02-03 05:37:57","closed_at":"2026-02-03 05:37:57","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1tlk","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["detection","foundation"]}
-{"id":"i-31u0","uuid":"900cf512-3ed8-47d7-a6bb-3ea7e8668e43","title":"Implement machine ID generation and storage","content":"## Overview\nGenerate a unique machine identifier for registry tracking, stored in global config.\n\n## Acceptance Criteria\n- [ ] `getMachineId()` returns consistent ID for this machine\n- [ ] ID format: `{hostname}-{random-suffix}` (e.g., `macbook-pro-a1b2`)\n- [ ] Generated once on first use, stored in global config\n- [ ] Random suffix is 4 hex characters\n- [ ] Function is idempotent (same ID on repeated calls)\n\n## Technical Notes\n- Use `os.hostname()` for hostname\n- Use `crypto.randomBytes(2).toString('hex')` for suffix\n- Store in `~/.config/minimem/config.json` as `machineId`\n\n## Implements\n[[s-2wx5]] - Machine ID for registry","status":"closed","priority":0,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:10","updated_at":"2026-02-03 05:36:54","closed_at":"2026-02-03 05:36:54","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-31u0","from_type":"issue","to":"i-dvoe","to_type":"issue","type":"blocks"},{"from":"i-31u0","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["config","foundation"]}
-{"id":"i-1ce6","uuid":"ec0bde24-9cb6-4545-88bb-87f7c552d028","title":"Implement central repo initialization (sync init-central)","content":"## Overview\nCreate a new central repository for syncing memories, or configure an existing repo as central.\n\n## Acceptance Criteria\n- [ ] `minimem sync init-central <path>` creates new central repo:\n  - Initializes git repo if not exists\n  - Creates `.gitignore` (ignores `*.db`, `staging/`, `conflicts/`)\n  - Creates empty `.minimem-registry.json`\n  - Creates README.md explaining the repo\n- [ ] If path is existing git repo, adds registry file if missing\n- [ ] Warns if existing repo has unusual structure\n- [ ] Sets `centralRepo` in global config after creation\n- [ ] Validates path is writable\n\n## Technical Notes\n- Use `simple-git` for git operations\n- Create directory structure atomically\n\n## Implements\n[[s-2wx5]] - Bootstrap Flow A","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:17","updated_at":"2026-02-03 05:40:19","closed_at":"2026-02-03 05:40:19","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1ce6","from_type":"issue","to":"i-1ll7","to_type":"issue","type":"blocks"},{"from":"i-1ce6","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["bootstrap","central-repo","cli"]}
-{"id":"i-dvoe","uuid":"ad511324-6191-4e0c-bbf4-5be94f92a63e","title":"Implement registry system for path collision prevention","content":"## Overview\nManage the `.minimem-registry.json` file in central repo to track all sync mappings and prevent path collisions.\n\n## Acceptance Criteria\n- [ ] Registry schema with mappings array:\n  - `path`: central repo path\n  - `localPath`: local directory path\n  - `machineId`: machine identifier\n  - `lastSync`: ISO timestamp\n- [ ] `readRegistry(centralRepo)` loads registry\n- [ ] `writeRegistry(centralRepo, registry)` saves registry\n- [ ] `checkCollision(registry, path, localPath, machineId)` returns:\n  - `none`: path is free\n  - `same-machine`: can remap (update)\n  - `collision`: different machine has this path\n- [ ] `addMapping(registry, mapping)` adds/updates entry\n- [ ] `removeMapping(registry, path, machineId)` removes entry\n- [ ] Registry file is created if missing\n\n## Technical Notes\n- Atomic writes (write to temp, rename)\n- Handle concurrent access gracefully\n\n## Implements\n[[s-2wx5]] - Central Repo Registry","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:22","updated_at":"2026-02-03 05:40:20","closed_at":"2026-02-03 05:40:20","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-dvoe","from_type":"issue","to":"i-1ll7","to_type":"issue","type":"blocks"},{"from":"i-dvoe","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["central-repo","registry"]}
-{"id":"i-1ll7","uuid":"9ea75ed5-2fa2-430b-87d1-4f7a7f518d4a","title":"Implement sync init command with collision validation","content":"## Overview\nInitialize sync for a memory directory, mapping it to a path in the central repo with collision checking.\n\n## Acceptance Criteria\n- [ ] `minimem sync init --path <central-path>` for current directory\n- [ ] `minimem sync init --local <dir> --path <central-path>` for explicit directory\n- [ ] Validates central repo is configured\n- [ ] Checks registry for path collisions, blocks if collision detected\n- [ ] Creates `.minimem/config.json` with sync settings\n- [ ] Registers mapping in central repo registry\n- [ ] Performs initial sync (pull if central has content, push if local-only)\n- [ ] Shows clear error messages for:\n  - Central repo not configured\n  - Path already mapped by different directory\n  - Local directory doesn't exist\n\n## Technical Notes\n- Requires: config system, registry system, machine ID\n- Initial sync direction based on which side has content\n\n## Implements\n[[s-2wx5]] - Bootstrap Flow C","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:29","updated_at":"2026-02-03 05:42:51","closed_at":"2026-02-03 05:42:51","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-1ll7","from_type":"issue","to":"i-7gne","to_type":"issue","type":"blocks"},{"from":"i-1ll7","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","sync-setup"]}
-{"id":"i-7gne","uuid":"b793a113-8ab4-4921-82e7-273f16320a0a","title":"Implement sync list and sync remove commands","content":"## Overview\nCommands to view all sync mappings and remove a directory from sync.\n\n## Acceptance Criteria\n- [ ] `minimem sync list` shows all mappings from registry:\n  - Central path\n  - Local path\n  - Machine ID\n  - Last sync time\n  - Highlights current machine's mappings\n- [ ] `minimem sync remove` removes current directory from sync:\n  - Removes from local `.minimem/config.json`\n  - Removes from central repo registry\n  - Does NOT delete synced files (just unlinks)\n- [ ] `minimem sync remove --local <dir>` for explicit directory\n- [ ] Confirms before removing\n\n## Technical Notes\n- Read registry from central repo\n- Format output as table\n\n## Implements\n[[s-2wx5]] - CLI commands for sync management","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:33","updated_at":"2026-02-03 05:42:57","closed_at":"2026-02-03 05:42:57","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7gne","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","sync-setup"]}
-{"id":"i-8gam","uuid":"4450c802-d293-45e1-8a6b-76c476764814","title":"Implement sync state tracking with content hashing","content":"## Overview\nTrack the sync state of files using content hashes to detect changes and conflicts.\n\n## Acceptance Criteria\n- [ ] Sync state stored in `.minimem/sync-state.json`:\n  - `lastSync`: ISO timestamp\n  - `files`: map of filename to hash info\n- [ ] Each file entry has:\n  - `localHash`: SHA-256 of local content\n  - `remoteHash`: SHA-256 of remote content\n  - `lastSyncedHash`: hash at last successful sync\n- [ ] `computeFileHash(filePath)` returns SHA-256 hex\n- [ ] `loadSyncState(dir)` reads state file\n- [ ] `saveSyncState(dir, state)` writes state file\n- [ ] `updateSyncState(dir, files)` updates hashes after sync\n- [ ] Handles missing state file (first sync)\n\n## Technical Notes\n- Use `crypto.createHash('sha256')`\n- Atomic writes for state file\n- Only track files matching include/exclude patterns\n\n## Implements\n[[s-2wx5]] - Conflict Detection (Hash + Shadow)","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:41","updated_at":"2026-02-03 05:42:50","closed_at":"2026-02-03 05:42:50","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-8gam","from_type":"issue","to":"i-3jn4","to_type":"issue","type":"blocks"},{"from":"i-8gam","from_type":"issue","to":"i-5ooa","to_type":"issue","type":"blocks"},{"from":"i-8gam","from_type":"issue","to":"i-9fm3","to_type":"issue","type":"blocks"},{"from":"i-8gam","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["core-sync","state"]}
-{"id":"i-5ooa","uuid":"17bc44e4-1373-4fde-8114-06320d27b71e","title":"Implement push command","content":"## Overview\nPush local memory files to the central repository.\n\n## Acceptance Criteria\n- [ ] `minimem push` syncs current directory to central repo\n- [ ] `minimem push --dir <path>` for explicit directory\n- [ ] Only pushes files matching include/exclude patterns\n- [ ] Uses atomic staging:\n  1. Copy to `.minimem/staging/{timestamp}/`\n  2. Validate all files copied\n  3. Move to central repo path\n  4. Clean up staging\n- [ ] Updates sync state after successful push\n- [ ] Updates registry `lastSync` timestamp\n- [ ] Detects conflicts (both sides changed) and delegates to conflict handler\n- [ ] Shows summary: files pushed, conflicts found, errors\n\n## Technical Notes\n- Requires: sync state, config, registry\n- Use conflict detection before overwriting\n\n## Implements\n[[s-2wx5]] - Push command","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:46","updated_at":"2026-02-03 05:45:16","closed_at":"2026-02-03 05:45:16","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-5ooa","from_type":"issue","to":"i-25ys","to_type":"issue","type":"blocks"},{"from":"i-5ooa","from_type":"issue","to":"i-7l8f","to_type":"issue","type":"blocks"},{"from":"i-5ooa","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","core-sync"]}
-{"id":"i-3jn4","uuid":"5c9b07bf-718d-47b2-bc32-5b19b9087d33","title":"Implement pull command","content":"## Overview\nPull memory files from the central repository to local directory.\n\n## Acceptance Criteria\n- [ ] `minimem pull` syncs central repo to current directory\n- [ ] `minimem pull --dir <path>` for explicit directory\n- [ ] Only pulls files matching include/exclude patterns\n- [ ] Uses atomic staging:\n  1. Copy from central to `.minimem/staging/{timestamp}/`\n  2. Validate all files copied\n  3. Move to local directory\n  4. Clean up staging\n- [ ] Updates sync state after successful pull\n- [ ] Detects conflicts (both sides changed) and delegates to conflict handler\n- [ ] Shows summary: files pulled, conflicts found, errors\n- [ ] Creates local directories as needed\n\n## Technical Notes\n- Requires: sync state, config, registry\n- Mirror of push logic but reversed direction\n\n## Implements\n[[s-2wx5]] - Pull command","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:48","updated_at":"2026-02-03 05:45:16","closed_at":"2026-02-03 05:45:16","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3jn4","from_type":"issue","to":"i-25ys","to_type":"issue","type":"blocks"},{"from":"i-3jn4","from_type":"issue","to":"i-7l8f","to_type":"issue","type":"blocks"},{"from":"i-3jn4","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","core-sync"]}
-{"id":"i-9fm3","uuid":"f5cb95c3-ba65-4ffe-a863-da414d6dc801","title":"Implement conflict detection algorithm","content":"## Overview\nDetect when both local and remote have changed since last sync, requiring conflict resolution.\n\n## Acceptance Criteria\n- [ ] `detectConflicts(dir, centralRepo)` returns list of:\n  - `file`: filename\n  - `status`: `no-change` | `local-only` | `remote-only` | `conflict`\n  - `localHash`, `remoteHash`, `baseHash`\n- [ ] Algorithm per file:\n  - If localHash == remoteHash → `no-change`\n  - If localHash == baseHash → `remote-only` (pull)\n  - If remoteHash == baseHash → `local-only` (push)\n  - Else → `conflict`\n- [ ] Creates shadow copy for conflicts:\n  - `.minimem/shadows/{filename}.base` from lastSyncedHash content\n- [ ] Handles new files (no base hash)\n- [ ] Handles deleted files\n\n## Technical Notes\n- Shadow copies needed for 3-way merge\n- Consider file renames (future enhancement)\n\n## Implements\n[[s-2wx5]] - Conflict Detection Algorithm","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:56:56","updated_at":"2026-02-03 05:45:12","closed_at":"2026-02-03 05:45:12","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-9fm3","from_type":"issue","to":"i-3jn4","to_type":"issue","type":"blocks"},{"from":"i-9fm3","from_type":"issue","to":"i-5ooa","to_type":"issue","type":"blocks"},{"from":"i-9fm3","from_type":"issue","to":"i-8t0z","to_type":"issue","type":"blocks"},{"from":"i-9fm3","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["conflict","core-sync"]}
-{"id":"i-8t0z","uuid":"f4a413ac-3349-4d99-9c24-b6ba0cbe982e","title":"Implement merge resolution strategies","content":"## Overview\nApply configured merge strategy when conflicts are detected.\n\n## Acceptance Criteria\n- [ ] `resolveConflict(file, strategy, options)` applies strategy:\n  - `keep-both`: Append both with conflict markers and timestamps\n  - `merge`: Git-style 3-way merge using diff3\n  - `manual`: Move to quarantine, fail sync for this file\n  - `last-write-wins`: Use file with later mtime\n- [ ] Keep-both format:\n  ```\n  <<<<<<< LOCAL (2024-01-15 10:30)\n  local content\n  =======\n  remote content\n  >>>>>>> REMOTE (2024-01-15 09:45)\n  ```\n- [ ] Merge resolver hook support:\n  - If `mergeResolver` configured, spawn external tool\n  - Wait for tool to exit\n  - Read merged result\n- [ ] Returns: `resolved` | `quarantined` | `failed`\n\n## Technical Notes\n- Use `diff3` or similar for 3-way merge\n- External tools get paths: base, local, remote, output\n\n## Implements\n[[s-2wx5]] - Merge Resolution Strategies","status":"closed","priority":1,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:02","updated_at":"2026-02-03 05:45:17","closed_at":"2026-02-03 05:45:17","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-8t0z","from_type":"issue","to":"i-9a8e","to_type":"issue","type":"blocks"},{"from":"i-8t0z","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["conflict","merge"]}
-{"id":"i-9a8e","uuid":"57a30353-f397-4bce-9478-3b429da858ee","title":"Implement quarantine and recovery system","content":"## Overview\nQuarantine conflicted files and provide recovery commands for failed syncs.\n\n## Acceptance Criteria\n- [ ] Quarantine structure:\n  ```\n  .minimem/conflicts/{timestamp}/\n  ├── {filename}.local\n  ├── {filename}.remote\n  └── {filename}.base\n  ```\n- [ ] `quarantineConflict(file, local, remote, base)` saves copies\n- [ ] `minimem sync conflicts` lists all quarantined conflicts:\n  - Timestamp, filename, local/remote timestamps\n- [ ] `minimem sync resolve <file>` opens merge tool for manual resolution\n- [ ] `minimem sync recover` retries last failed sync\n- [ ] Sync log at `.minimem/sync.log`:\n  - Timestamp, operation, result, errors\n- [ ] Cleanup old quarantine (configurable retention)\n\n## Technical Notes\n- Quarantine preserves all versions for safety\n- Recovery reads from staging if present\n\n## Implements\n[[s-2wx5]] - Sync Failure Recovery","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:08","updated_at":"2026-02-03 07:24:05","closed_at":"2026-02-03 07:24:05","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-9a8e","from_type":"issue","to":"i-65zj","to_type":"issue","type":"blocks"},{"from":"i-9a8e","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","conflict","recovery"],"feedback":[{"id":"c65a26ed-b934-4357-89e3-05ab096f6ced","from_id":"i-9a8e","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented quarantine and recovery system:\n- Quarantine structure in `.minimem/conflicts/{timestamp}/` with `.local`, `.remote`, `.base` files\n- `quarantineConflict()` and `listQuarantinedConflicts()` in conflicts.ts\n- CLI commands: `sync:conflicts`, `sync:resolve <timestamp>`, `sync:cleanup`\n- Sync log at `.minimem/sync.log` with JSONL format\n- `sync:log` command to view history\n- Auto-detects merge tools (code, meld, kdiff3, vimdiff)\n- Cleanup supports --days and --dry-run options","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T07:24:04.899Z","updated_at":"2026-02-03T07:24:04.899Z"}]}
-{"id":"i-7l8f","uuid":"95c7277b-dfb0-47c0-8092-51116a648069","title":"Implement file watcher with debouncing","content":"## Overview\nWatch memory directories for file changes with debouncing to avoid rapid-fire syncs.\n\n## Acceptance Criteria\n- [ ] `createFileWatcher(dir, options)` returns watcher instance\n- [ ] Watches files matching include/exclude patterns\n- [ ] Debounces changes (default 2 seconds):\n  - Multiple rapid changes trigger single callback\n  - Configurable debounce interval\n- [ ] Emits events: `change`, `add`, `unlink`\n- [ ] Ignores `.minimem/` directory (staging, conflicts, db)\n- [ ] `watcher.close()` cleans up\n- [ ] Works cross-platform (macOS, Linux, Windows)\n\n## Technical Notes\n- Use `chokidar` for cross-platform watching\n- Debounce per-file or batch all changes\n- Consider `usePolling` fallback for network drives\n\n## Implements\n[[s-2wx5]] - Daemon file watching","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:15","updated_at":"2026-02-03 07:30:17","closed_at":"2026-02-03 07:30:17","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-7l8f","from_type":"issue","to":"i-3ko0","to_type":"issue","type":"blocks"},{"from":"i-7l8f","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["daemon","watcher"],"feedback":[{"id":"9ec16de1-c190-4de5-871d-80cd5eebdf1d","from_id":"i-7l8f","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented file watcher with debouncing in src/cli/sync/watcher.ts:\n- `createFileWatcher(dir, options)` returns watcher instance\n- Watches files matching include/exclude patterns (default: MEMORY.md, memory/*.md)\n- Debounces changes (default 2 seconds, configurable)\n- Emits batched 'changes' events with event type (add, change, unlink)\n- Ignores .minimem/ directory automatically\n- `createMultiDirWatcher()` for watching multiple directories\n- Uses chokidar for cross-platform support\n- Supports usePolling option for network drives\n- `watcher.close()` cleans up resources","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T07:30:17.354Z","updated_at":"2026-02-03T07:30:17.354Z"}]}
-{"id":"i-3ko0","uuid":"d113f827-40c7-4072-9c1e-d7b95c10c661","title":"Implement daemon core with auto-sync","content":"## Overview\nBackground daemon that watches configured directories and syncs automatically.\n\n## Acceptance Criteria\n- [ ] `minimem daemon` starts daemon in foreground\n- [ ] `minimem daemon --background` detaches (writes PID file)\n- [ ] `minimem daemon stop` stops running daemon\n- [ ] `minimem daemon status` shows daemon state\n- [ ] Daemon behavior:\n  - Reads all directories with sync config from registry\n  - Starts file watcher for each\n  - On local change: triggers push (if autoSync enabled)\n  - Watches central repo for changes (polling or git hooks)\n  - On central change: triggers pull to affected directories\n- [ ] Respects `autoCommit` setting (stage only vs commit)\n- [ ] Logs activity to `.minimem/daemon.log`\n- [ ] Graceful shutdown on SIGTERM/SIGINT\n\n## Technical Notes\n- Use PID file for singleton daemon\n- Consider systemd/launchd integration later\n\n## Implements\n[[s-2wx5]] - Daemon Architecture","status":"closed","priority":2,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:21","updated_at":"2026-02-03 07:32:36","closed_at":"2026-02-03 07:32:36","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-3ko0","from_type":"issue","to":"i-5skx","to_type":"issue","type":"blocks"},{"from":"i-3ko0","from_type":"issue","to":"i-65zj","to_type":"issue","type":"blocks"},{"from":"i-3ko0","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["auto-sync","daemon"],"feedback":[{"id":"a6defc05-2fc0-4c4c-ba67-33e9a311330e","from_id":"i-3ko0","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented daemon core in src/cli/sync/daemon.ts and src/cli/commands/daemon.ts:\n- `minimem daemon` starts daemon in foreground\n- `minimem daemon --background` detaches with PID file\n- `minimem daemon:stop` stops running daemon\n- `minimem daemon:status` shows daemon state\n- `minimem daemon:logs` shows daemon log with -f/--follow option\n- Daemon reads sync-enabled directories from registry\n- Auto-syncs on local changes when autoSync is enabled\n- Polls central repo for remote changes\n- Logs activity to ~/.minimem/daemon.log with rotation\n- Graceful shutdown on SIGTERM/SIGINT","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T07:32:36.150Z","updated_at":"2026-02-03T07:32:36.150Z"}]}
-{"id":"i-5skx","uuid":"66e3932f-7064-4d65-a2f5-8c40dd69ed76","title":"Implement registry validation in daemon","content":"## Overview\nDaemon periodically validates registry for path collisions and warns users.\n\n## Acceptance Criteria\n- [ ] Daemon checks registry on startup\n- [ ] Periodic validation (configurable interval, default 5 minutes)\n- [ ] Detects invalid states:\n  - Same path mapped by multiple machines\n  - Stale mappings (machine not seen in X days)\n  - Local directory no longer exists\n- [ ] Warnings logged and optionally shown to user\n- [ ] Does not auto-fix, just warns\n- [ ] `minimem sync validate` manual validation command\n\n## Technical Notes\n- Avoid spamming warnings (once per issue per session)\n- Consider notification system integration\n\n## Implements\n[[s-2wx5]] - Daemon validates registry","status":"closed","priority":3,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:25","updated_at":"2026-02-03 07:35:11","closed_at":"2026-02-03 07:35:11","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-5skx","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["daemon","registry","validation"],"feedback":[{"id":"7235dfb2-ab25-4b72-b673-e9472ae54bdf","from_id":"i-5skx","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented registry validation in src/cli/sync/validation.ts:\n- Detects path collisions (same path mapped by different machines)\n- Detects stale mappings (not synced in 30+ days)\n- Detects missing local directories (for current machine only)\n- `minimem sync:validate` CLI command with JSON output option\n- Daemon validates registry on startup and periodically (every 5 minutes)\n- Warnings logged to daemon.log without spamming","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T07:35:11.209Z","updated_at":"2026-02-03T07:35:11.209Z"}]}
-{"id":"i-25ys","uuid":"93fdc287-ae2b-49fa-905f-d109eb12da84","title":"Implement sync status command","content":"## Overview\nShow sync status across all configured directories.\n\n## Acceptance Criteria\n- [ ] `minimem sync status` shows for each synced directory:\n  - Local path\n  - Central repo path\n  - Last sync time\n  - Status: `synced` | `local-changes` | `remote-changes` | `conflicts`\n  - Number of pending changes\n- [ ] `minimem sync status --dir <path>` for specific directory\n- [ ] Color-coded output (green=synced, yellow=changes, red=conflicts)\n- [ ] Shows daemon status (running/stopped)\n- [ ] Quick summary line at end\n\n## Technical Notes\n- Reads sync state files\n- Compares current hashes to detect pending changes\n- Does not perform sync, just reports\n\n## Implements\n[[s-2wx5]] - Status command (nice to have)","status":"closed","priority":3,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:32","updated_at":"2026-02-03 07:20:56","closed_at":"2026-02-03 07:20:56","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-25ys","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["cli","status"],"feedback":[{"id":"b06307fd-5ecc-4c1c-ad85-bce61065228e","from_id":"i-25ys","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented sync:status command in src/cli/commands/push-pull.ts. Shows sync status with counts for unchanged, local changes, remote changes, new files, deleted files, and conflicts. Color-coding deferred to future enhancement. Daemon status will be added when daemon is implemented.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T07:20:56.704Z","updated_at":"2026-02-03T07:20:56.704Z"}]}
-{"id":"i-65zj","uuid":"3f63eb98-b13e-4ba9-8a97-7e2b28d019ce","title":"Write integration tests for git sync system","content":"## Overview\nEnd-to-end tests for the complete sync workflow.\n\n## Acceptance Criteria\n- [ ] Test bootstrap flows:\n  - Fresh central repo creation\n  - Existing repo as central\n  - Directory sync init\n  - Clone setup on \"new machine\" (simulated)\n- [ ] Test sync operations:\n  - Push local changes\n  - Pull remote changes\n  - Bidirectional sync\n- [ ] Test conflict scenarios:\n  - Both sides changed, keep-both resolution\n  - Conflict quarantine\n  - Recovery from failed sync\n- [ ] Test collision prevention:\n  - Block duplicate path mapping\n  - Allow same-machine remap\n- [ ] Test daemon (if feasible):\n  - Auto-sync on file change\n  - Registry validation warnings\n- [ ] Use temp directories, no real git remotes\n\n## Technical Notes\n- Mock git operations or use real local repos\n- Clean up temp directories after tests\n- Consider test isolation\n\n## Implements\n[[s-2wx5]] - Success Criteria validation","status":"closed","priority":3,"assignee":null,"archived":0,"archived_at":null,"created_at":"2026-02-02 23:57:37","updated_at":"2026-02-03 18:40:36","closed_at":"2026-02-03 18:40:36","parent_id":null,"parent_uuid":null,"relationships":[{"from":"i-65zj","from_type":"issue","to":"s-2wx5","to_type":"spec","type":"implements"}],"tags":["integration","testing"],"feedback":[{"id":"ee25b64f-eaa8-4f55-ae5f-73863958c6a6","from_id":"i-65zj","to_id":"s-2wx5","feedback_type":"comment","content":"Implemented comprehensive integration tests in src/cli/sync/__tests__/integration.test.ts:\n\n**Bootstrap Flows:**\n- Fresh central repo creation and validation\n- XDG config setup with central repo path\n- Directory sync initialization\n- Clone setup simulation on \"new machine\"\n\n**Sync Operations:**\n- Push local changes to central\n- Pull remote changes to local\n- Bidirectional sync\n\n**Conflict Scenarios:**\n- Detect conflicts when both sides changed\n- Keep-both strategy for conflict resolution\n- Quarantine conflicts for manual resolution\n\n**Collision Prevention:**\n- Block duplicate path mapping from different machines\n- Allow same machine to remap path\n- Allow different paths for different machines\n- Detect collisions in validation\n\n**Full Workflow Test:**\n- Complete end-to-end sync workflow covering all components\n\nTotal: 133 tests across 10 test files, all passing.","agent":"alexngai","anchor":null,"dismissed":false,"created_at":"2026-02-03T18:40:35.831Z","updated_at":"2026-02-03T18:40:35.831Z"}]}

package/references/minimem/.sudocode/specs.jsonl

@@ -1 +0,0 @@
-{"id":"s-2wx5","uuid":"f2e6f765-0ff1-40ee-b93c-4ea832231e94","title":"Git Sync System for Memory Directories","file_path":"specs/s-2wx5_git_sync_system_for_memory_directories.md","content":"# Git Sync System for Memory Directories\n\n## Context\n\nminimem stores memories as plain Markdown files which are inherently git-friendly. However, users need a way to sync memories across machines and collaborate with others. The SQLite database with embeddings is **not** the source of truth and should never be committed—it's rebuilt locally via `minimem sync`.\n\nUsers have two distinct use cases:\n1. **Project-bound memories** - embedded directly in code repos alongside source code\n2. **Standalone memories** - scattered directories that should sync to a central repository\n3. **Hybrid** - project memories that are ALSO synced to a central repo for aggregation\n\n## Out of Scope\n\n- Real-time collaborative editing (not Google Docs)\n- Full git client replacement (we use git, not replace it)\n- Remote repository hosting (user provides their own)\n- Encryption at rest (use git-crypt or similar if needed)\n\n## Requirements\n\n### Must Have\n\n- [ ] CLI commands to configure sync mappings between local directories and central repo paths\n- [ ] Auto-detection of directory type (project-bound, standalone, hybrid)\n- [ ] Push/pull commands to sync directories with central repo\n- [ ] Configurable merge resolution strategies\n- [ ] Support for multiple directories syncing to one central repo\n- [ ] Path collision validation on init\n- [ ] Graceful sync failure recovery with atomic operations\n\n### Should Have\n\n- [ ] Daemon for automatic sync with file watching\n- [ ] Git hooks integration in central repo (post-pull triggers local sync)\n- [ ] Merge resolver hook for custom conflict resolution tools\n- [ ] Sync state registry in central repo to detect collisions\n\n### Nice to Have\n\n- [ ] Integration with MCP server (daemon runs alongside)\n- [ ] Periodic sync fallback when file watching unavailable\n- [ ] Status command showing sync state across all configured directories\n\n## Design\n\n### Directory Types\n\n| Type | Detection | Git Management | Sync Behavior |\n|------|-----------|----------------|---------------|\n| **Project-bound** | Inside git repo, no sync config | User handles git | No sync |\n| **Standalone** | Has sync config, not in project git | minimem manages | Full sync |\n| **Hybrid** | Inside git repo AND has sync config | User handles project git | Also syncs to central |\n| **Unmanaged** | No git repo, no sync config | None | Prompt to set up |\n\n### Auto-Detection Logic\n\n```\nIs there a sync config in .minimem/config.json?\n├─ Yes: \n│   └─ Is directory inside a git repo?\n│       ├─ Yes → Hybrid (user manages project git, minimem syncs to central)\n│       └─ No  → Standalone (minimem manages sync)\n└─ No:\n    └─ Is directory inside a git repo?\n        ├─ Yes → Project-bound (user manages everything)\n        └─ No  → Unmanaged (prompt to set up sync?)\n```\n\n### Configuration\n\n**Global config** (`~/.config/minimem/config.json`):\n```json\n{\n  \"centralRepo\": \"~/memories-repo\",\n  \"sync\": {\n    \"conflictStrategy\": \"keep-both\",\n    \"autoSync\": true,\n    \"autoCommit\": false\n  }\n}\n```\n\n**Per-directory config** (`.minimem/config.json`):\n```json\n{\n  \"sync\": {\n    \"enabled\": true,\n    \"path\": \"global/\",\n    \"include\": [\"MEMORY.md\", \"memory/**/*.md\"],\n    \"exclude\": [\"memory/drafts/**\"]\n  }\n}\n```\n\n**Default sync scope:** `MEMORY.md` + `memory/**/*.md`\n\n### Central Repo Registry\n\nThe central repo maintains a registry to prevent path collisions:\n\n**`.minimem-registry.json`** (in central repo root):\n```json\n{\n  \"mappings\": [\n    {\n      \"path\": \"global/\",\n      \"localPath\": \"~/.minimem\",\n      \"machineId\": \"macbook-pro-a1b2\",\n      \"lastSync\": \"2024-01-15T10:30:00Z\"\n    },\n    {\n      \"path\": \"work/\",\n      \"localPath\": \"~/work/memories\",\n      \"machineId\": \"macbook-pro-a1b2\",\n      \"lastSync\": \"2024-01-15T10:30:00Z\"\n    }\n  ]\n}\n```\n\n**Collision detection:**\n- On `sync init`: check registry, block if path already mapped by different local path\n- Daemon: periodically validate registry, warn on conflicts\n- Same machine can remap (update), different machine with same path = collision\n\n### CLI Commands\n\n```bash\n# === Central Repo Setup ===\n\n# Use existing repo as central\nminimem config set centralRepo ~/existing-memories-repo\n\n# Initialize new central repo\nminimem sync init-central ~/new-memories-repo\n# Creates repo structure, .gitignore, registry file\n\n# === Directory Sync Setup ===\n\n# Initialize sync for current directory\nminimem sync init --path global/\n# Validates path not already mapped, updates registry\n\n# Explicit paths\nminimem sync init --local ~/work/memories --path work/\n\n# List all sync mappings (from registry)\nminimem sync list\n\n# Remove mapping\nminimem sync remove\n# Removes from local config and registry\n\n# === Sync Operations ===\n\nminimem push              # local → central repo\nminimem pull              # central repo → local\nminimem sync status       # show sync state for all directories\n```\n\n### Conflict Detection (Hybrid: Hash + Shadow)\n\n**Sync state tracking** (`.minimem/sync-state.json`):\n```json\n{\n  \"lastSync\": \"2024-01-15T10:30:00Z\",\n  \"files\": {\n    \"MEMORY.md\": {\n      \"localHash\": \"abc123\",\n      \"remoteHash\": \"abc123\",\n      \"lastSyncedHash\": \"abc123\"\n    },\n    \"memory/2024-01-15.md\": {\n      \"localHash\": \"def456\",\n      \"remoteHash\": \"def456\",\n      \"lastSyncedHash\": \"def456\"\n    }\n  }\n}\n```\n\n**Detection algorithm:**\n```\nFor each file:\n  localHash = hash(local file)\n  remoteHash = hash(central repo file)\n  baseHash = lastSyncedHash from sync-state.json\n  \n  if localHash == remoteHash:\n    → No change, skip\n  elif localHash == baseHash:\n    → Only remote changed, pull\n  elif remoteHash == baseHash:\n    → Only local changed, push\n  else:\n    → Both changed, CONFLICT\n    → Create shadow copy for 3-way merge\n    → Apply merge strategy\n```\n\n**Shadow copies** (created only on conflict):\n- `.minimem/shadows/{filename}.base` - last synced version\n- Used as merge base for 3-way merge\n- Cleaned up after resolution\n\n### Merge Resolution Strategies\n\n| Strategy | Behavior | Use Case |\n|----------|----------|----------|\n| `merge` | Git-style 3-way merge | Technical content |\n| `keep-both` | Append both versions with separator | **Default for memories** |\n| `manual` | Fail, open in merge tool | Critical content |\n| `last-write-wins` | Overwrite with latest timestamp | Low-stakes |\n\n**Keep-both format:**\n```markdown\n<<<<<<< LOCAL (2024-01-15 10:30)\nLocal version of content\n=======\nRemote version of content\n>>>>>>> REMOTE (2024-01-15 09:45)\n```\n\nMerge resolver hook:\n```json\n{\n  \"sync\": {\n    \"conflictStrategy\": \"manual\",\n    \"mergeResolver\": \"code --wait --merge\"\n  }\n}\n```\n\n### Sync Failure Recovery (Atomic + Quarantine)\n\n**Atomic sync process:**\n```\n1. Create staging: .minimem/staging/{timestamp}/\n2. Copy files to staging\n3. Validate all files copied successfully\n4. On success: move staging → final destination\n5. On failure: \n   - Leave staging intact\n   - Log error to .minimem/sync.log\n   - Notify user\n```\n\n**Quarantine for conflicts:**\n```\n.minimem/\n├── conflicts/\n│   └── 2024-01-15T10-30-00/\n│       ├── MEMORY.md.local\n│       ├── MEMORY.md.remote\n│       └── MEMORY.md.base\n└── staging/\n    └── {in-progress sync files}\n```\n\n**Recovery commands:**\n```bash\nminimem sync recover          # retry failed sync\nminimem sync conflicts        # list unresolved conflicts\nminimem sync resolve <file>   # manually resolve conflict\n```\n\n### Daemon Architecture\n\n```\n                    ┌─────────────────┐\n                    │     Daemon      │\n                    └────────┬────────┘\n                             │\n         ┌───────────────────┼───────────────────┐\n         │                   │                   │\n         ▼                   ▼                   ▼\n   Watch local dirs    Watch central repo    Validate registry\n   (file changes)      (git pull detected)   (detect collisions)\n         │                   │                   │\n         ▼                   ▼                   ▼\n   Debounce + Push     Pull to local dirs    Warn on conflicts\n```\n\n**Daemon responsibilities:**\n- Watch configured directories for file changes\n- Debounce rapid changes (e.g., 2 second delay)\n- Trigger push on local changes (if autoSync enabled)\n- Watch central repo for pulls (git hooks or polling)\n- Periodically validate registry for path collisions\n- Stage changes only by default (autoCommit: false)\n\nDaemon modes:\n- Standalone: `minimem daemon`\n- Integrated: runs with MCP server\n- System service: launchd/systemd\n\n### Bootstrap Flows\n\n**Flow A: Fresh central repo**\n```bash\nminimem sync init-central ~/memories-repo\n# Creates:\n#   ~/memories-repo/\n#   ├── .git/\n#   ├── .gitignore          # ignores *.db, staging/, conflicts/\n#   ├── .minimem-registry.json\n#   └── README.md\n\nminimem config set centralRepo ~/memories-repo\n```\n\n**Flow B: Existing repo as central**\n```bash\nminimem config set centralRepo ~/existing-repo\n# Validates repo exists\n# Creates .minimem-registry.json if missing\n# Warns if structure looks unusual\n```\n\n**Flow C: Add directory to sync**\n```bash\ncd ~/.minimem\nminimem sync init --path global/\n# Checks registry for collision\n# Updates .minimem/config.json\n# Registers in central repo\n# Initial sync (pull or push based on state)\n```\n\n**Flow D: Clone setup on new machine**\n```bash\ngit clone <central-repo> ~/memories-repo\nminimem config set centralRepo ~/memories-repo\nminimem sync list  # shows all registered paths\nminimem sync init --local ~/.minimem --path global/\n# Links local directory to existing central path\n# Updates registry with new machine ID\n# Pulls content from central\n```\n\n### Central Repo Structure\n\n```\nmemories-repo/                    # git repo\n├── .git/\n├── .gitignore\n├── .minimem-registry.json        # path collision prevention\n├── global/                       # maps to ~/.minimem/\n│   ├── MEMORY.md\n│   └── memory/\n├── work/                         # maps to ~/work/memories/\n│   ├── MEMORY.md\n│   └── memory/\n└── projects/\n    └── projectA/                 # hybrid: also in project repo\n        ├── MEMORY.md\n        └── memory/\n```\n\n## Success Criteria\n\n- [ ] User can configure a central repo and map multiple directories to it\n- [ ] `minimem push/pull` correctly syncs files between local and central\n- [ ] Conflicts are detected using hash comparison and resolved with keep-both strategy\n- [ ] Path collisions are prevented via registry validation on init\n- [ ] Auto-detection correctly identifies all four directory types\n- [ ] Sync failures are recoverable via atomic operations and quarantine\n- [ ] Daemon watches for changes and syncs automatically when enabled\n- [ ] Daemon detects and warns about registry conflicts\n\n## Technical Considerations\n\n- Use `chokidar` for cross-platform file watching\n- Git operations via `simple-git` library\n- Debounce file changes (2 second default) before sync\n- Content hashing with SHA-256 for conflict detection\n- Machine ID from `os.hostname()` + random suffix on first run\n- Store machine ID in global config\n- Central repo only contains `.md` files, registry, and gitignore\n\n## Decisions Made\n\n| Question | Decision | Rationale |\n|----------|----------|-----------|\n| Daemon auto-commit? | Configurable, default off | User controls when to commit |\n| Conflict strategy default? | `keep-both` | Never lose memory data |\n| Lock mechanism? | Atomic staging | Simpler than locks, same safety |\n| Path collision handling? | Registry + validation on init | Prevent rather than recover |\n","priority":1,"archived":0,"archived_at":null,"created_at":"2026-02-02 06:36:19","updated_at":"2026-02-02 23:50:18","parent_id":null,"parent_uuid":null,"relationships":[],"tags":["cli","daemon","git","sync"]}