cognitive-core 0.2.0 → 0.2.2

package/references/agent-workspace/tests/writers.test.ts

@@ -1,108 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import * as os from 'os';
-import { writeJson, writeJsonl, writeMarkdown, writeRaw, copyDir, symlink } from '../src/index.js';
-
-describe('Writers', () => {
-  let dir: string;
-
-  beforeEach(async () => {
-    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-writers-'));
-  });
-
-  afterEach(async () => {
-    await fs.rm(dir, { recursive: true, force: true });
-  });
-
-  describe('writeJson', () => {
-    it('writes pretty-printed JSON with trailing newline', async () => {
-      await writeJson(dir, 'data.json', { foo: 'bar', num: 42 });
-      const content = await fs.readFile(path.join(dir, 'data.json'), 'utf-8');
-      expect(content).toBe('{\n  "foo": "bar",\n  "num": 42\n}\n');
-    });
-
-    it('creates subdirectories as needed', async () => {
-      await writeJson(dir, 'nested/deep/data.json', { ok: true });
-      const content = await fs.readFile(path.join(dir, 'nested/deep/data.json'), 'utf-8');
-      expect(JSON.parse(content)).toEqual({ ok: true });
-    });
-  });
-
-  describe('writeJsonl', () => {
-    it('writes one JSON object per line', async () => {
-      const items = [{ a: 1 }, { b: 2 }, { c: 3 }];
-      await writeJsonl(dir, 'data.jsonl', items);
-      const content = await fs.readFile(path.join(dir, 'data.jsonl'), 'utf-8');
-      const lines = content.trimEnd().split('\n');
-      expect(lines).toHaveLength(3);
-      expect(JSON.parse(lines[0])).toEqual({ a: 1 });
-      expect(JSON.parse(lines[2])).toEqual({ c: 3 });
-    });
-  });
-
-  describe('writeMarkdown', () => {
-    it('writes markdown with YAML frontmatter', async () => {
-      await writeMarkdown(dir, 'doc.md', {
-        frontmatter: { title: 'Hello', tags: ['a', 'b'] },
-        body: '# Content\n\nSome text.',
-      });
-      const content = await fs.readFile(path.join(dir, 'doc.md'), 'utf-8');
-      expect(content).toContain('---\n');
-      expect(content).toContain('title: Hello');
-      expect(content).toContain('# Content');
-    });
-
-    it('writes markdown without frontmatter when empty', async () => {
-      await writeMarkdown(dir, 'plain.md', {
-        frontmatter: {},
-        body: '# Just body',
-      });
-      const content = await fs.readFile(path.join(dir, 'plain.md'), 'utf-8');
-      expect(content).not.toContain('---');
-      expect(content).toBe('# Just body\n');
-    });
-  });
-
-  describe('writeRaw', () => {
-    it('writes raw string content', async () => {
-      await writeRaw(dir, 'data.csv', 'a,b,c\n1,2,3\n');
-      const content = await fs.readFile(path.join(dir, 'data.csv'), 'utf-8');
-      expect(content).toBe('a,b,c\n1,2,3\n');
-    });
-  });
-
-  describe('copyDir', () => {
-    it('copies a directory tree', async () => {
-      // Create a source directory
-      const src = path.join(dir, '_src');
-      await fs.mkdir(path.join(src, 'sub'), { recursive: true });
-      await fs.writeFile(path.join(src, 'a.txt'), 'hello');
-      await fs.writeFile(path.join(src, 'sub', 'b.txt'), 'world');
-
-      const dest = path.join(dir, 'dest');
-      await fs.mkdir(dest, { recursive: true });
-      await copyDir(dest, 'copied', src);
-
-      const a = await fs.readFile(path.join(dest, 'copied', 'a.txt'), 'utf-8');
-      const b = await fs.readFile(path.join(dest, 'copied', 'sub', 'b.txt'), 'utf-8');
-      expect(a).toBe('hello');
-      expect(b).toBe('world');
-    });
-  });
-
-  describe('symlink', () => {
-    it('creates a symlink to a target', async () => {
-      const target = path.join(dir, 'target.txt');
-      await fs.writeFile(target, 'symlinked');
-
-      await symlink(dir, 'link.txt', target);
-
-      const content = await fs.readFile(path.join(dir, 'link.txt'), 'utf-8');
-      expect(content).toBe('symlinked');
-
-      const stat = await fs.lstat(path.join(dir, 'link.txt'));
-      expect(stat.isSymbolicLink()).toBe(true);
-    });
-  });
-});

package/references/agent-workspace/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist", "tests"]
-}

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

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

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"]}

package/references/minimem/CLAUDE.md

@@ -1,310 +0,0 @@
-# CLAUDE.md
-
-This file provides context for AI agents working on the minimem codebase.
-
-## Project Overview
-
-**minimem** is a file-based memory system with vector search for AI agents. It lets users store memories as Markdown files and search them semantically using embeddings.
-
-**Key value props:**
-- Plain Markdown files (git-friendly, human-readable)
-- Semantic search via embeddings (OpenAI, Gemini, or local)
-- Hybrid search combining vectors + full-text (BM25)
-- MCP server for Claude Desktop/Cursor integration
-- CLI for command-line usage
-
-## Architecture
-
-```
-src/
-├── minimem.ts          # Main Minimem class - core logic
-├── internal.ts         # Utilities: chunking, hashing, file listing
-├── index.ts            # Public exports
-├── cli/                # CLI implementation
-│   ├── index.ts        # Entry point, command registration
-│   ├── config.ts       # Config loading, directory resolution
-│   └── commands/       # Individual command implementations
-├── db/                 # Database layer
-│   ├── schema.ts       # SQLite schema creation (v4)
-│   └── sqlite-vec.ts   # Vector extension loading
-├── embeddings/         # Embedding providers
-│   ├── embeddings.ts   # Provider factory and interfaces
-│   ├── batch-openai.ts # OpenAI batch embedding
-│   └── batch-gemini.ts # Gemini batch embedding
-├── search/             # Search implementation
-│   ├── hybrid.ts       # Hybrid vector+FTS search, BM25
-│   ├── search.ts       # Knowledge-filtered search helpers
-│   └── graph.ts        # Knowledge graph traversal (BFS)
-└── server/             # MCP server
-    ├── mcp.ts          # MCP protocol implementation
-    └── tools.ts        # Tool definitions for LLM integration
-```
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `src/minimem.ts` | Core class with search, sync, append, knowledge methods |
-| `src/internal.ts` | `chunkMarkdown()`, `hashText()`, `listMemoryFiles()` |
-| `src/session.ts` | Frontmatter parsing/serialization (incl. knowledge fields) |
-| `src/cli/commands/search.ts` | Multi-directory search implementation |
-| `src/embeddings/embeddings.ts` | `createEmbeddingProvider()` factory |
-| `src/search/hybrid.ts` | `mergeHybridResults()`, BM25 scoring |
-| `src/search/search.ts` | `buildKnowledgeFilterSql()` for metadata filtering |
-| `src/search/graph.ts` | `getLinksFrom()`, `getLinksTo()`, `getNeighbors()`, `getPathBetween()` |
-| `src/server/mcp.ts` | MCP server for Claude Desktop integration |
-| `src/server/tools.ts` | MCP tool definitions (memory + knowledge) |
-
-## Development Commands
-
-```bash
-npm run build          # Build library and CLI
-npm run dev            # Watch mode
-npm run test           # Unit tests (vitest)
-npm run test:cli       # CLI command tests
-npm run test:integration  # E2E integration tests
-npm run test:all       # All tests
-```
-
-## Testing
-
-Tests are in `__tests__/` directories alongside source:
-
-- `src/__tests__/minimem.integration.test.ts` - Full E2E with mock embeddings
-- `src/__tests__/knowledge.test.ts` - Knowledge frontmatter parsing + graph traversal
-- `src/cli/__tests__/commands.test.ts` - CLI command tests
-- `src/embeddings/__tests__/` - Embedding provider tests
-- `src/search/__tests__/` - Hybrid search tests
-- `src/server/__tests__/` - MCP server + knowledge tool tests
-
-**Mock embeddings:** Tests use deterministic embeddings based on keyword presence (no API calls needed). See `createDeterministicEmbedding()` in test files.
-
-## Build System
-
-- **tsup** for bundling (ESM only, Node 22+)
-- Library: `dist/index.js` with types
-- CLI: `dist/cli/index.js` (bundled with shebang)
-- **postbuild** script fixes `node:sqlite` import (esbuild strips `node:` prefix)
-
-## Important Patterns
-
-### Memory Path Validation
-Only `MEMORY.md` and `memory/*.md` files are indexed. The `validateMemoryPath()` method enforces this.
-
-### Embedding Cache
-Embeddings are cached by content hash in SQLite. Same content = same embedding, even across files.
-
-### Hybrid Search
-Default weights: 70% vector similarity, 30% BM25 text search. Configurable via `hybrid.vectorWeight` and `hybrid.textWeight`.
-
-### Multi-Directory Search
-The search command can query multiple directories:
-```bash
-minimem search "query" --dir ~/a --dir ~/b --global
-```
-Results are merged and sorted by score.
-
-## Common Tasks
-
-### Adding a new CLI command
-
-1. Create `src/cli/commands/newcmd.ts`:
-```typescript
-export type NewCmdOptions = { dir?: string; global?: boolean; };
-
-export async function newcmd(options: NewCmdOptions): Promise<void> {
-  const memoryDir = resolveMemoryDir({ dir: options.dir, global: options.global });
-  // ... implementation
-}
-```
-
-2. Export from `src/cli/commands/index.ts`
-
-3. Register in `src/cli/index.ts`:
-```typescript
-program
-  .command("newcmd")
-  .description("Description")
-  .option("-d, --dir <path>", "Memory directory")
-  .action(newcmd);
-```
-
-4. Add tests in `src/cli/__tests__/commands.test.ts`
-
-### Adding a new embedding provider
-
-1. Add provider type to `EmbeddingProviderOptions` in `src/embeddings/embeddings.ts`
-2. Implement in `createEmbeddingProvider()` switch statement
-3. Add batch function in `src/embeddings/batch-{provider}.ts` if needed
-4. Update `auto` provider detection logic
-
-### Modifying the database schema
-
-1. Update `createSchema()` in `src/db/schema.ts` (currently at SCHEMA_VERSION 4)
-2. Consider migration strategy (currently: recreate on schema change)
-3. Update relevant queries in `src/minimem.ts`
-4. If adding knowledge-related columns, update `indexKnowledgeMetadata()` in `src/minimem.ts`
-
-## Gotchas
-
-1. **node:sqlite is experimental** - Requires Node 22+, shows warning on every run
-2. **sqlite-vec may not load** - Falls back to FTS-only search if extension fails
-3. **CLI bundle strips node: prefix** - postbuild script fixes this
-4. **Commander.js is CJS** - Must be external in CLI bundle, not inlined
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `OPENAI_API_KEY` | OpenAI embeddings |
-| `GOOGLE_API_KEY` | Gemini embeddings |
-| `GEMINI_API_KEY` | Alternative Gemini key |
-| `MEMORY_DIR` | Default memory directory |
-
-## File Structure Convention
-
-```
-project/
-├── MEMORY.md           # Main memory (required for init)
-├── memory/             # Additional memories
-│   ├── YYYY-MM-DD.md   # Daily logs (from append)
-│   └── *.md            # Topic files
-└── .minimem/
-    ├── config.json     # User config
-    ├── index.db        # SQLite with vectors
-    └── .gitignore      # Ignores index.db
-```
-
-## MCP Integration
-
-The MCP server exposes 5 tools over stdio, compatible with Claude Desktop and Cursor:
-
-| Tool | Purpose |
-|------|---------|
-| `memory_search` | General semantic search across all memory files |
-| `memory_get_details` | Retrieve full content of a specific memory file |
-| `knowledge_search` | Search knowledge notes with domain/entity/confidence/type filters |
-| `knowledge_graph` | Traverse knowledge graph relationships from a note |
-| `knowledge_path` | Find shortest path between two knowledge notes via graph links |
-
-The 3 `knowledge_*` tools are additive — they only return results when knowledge-formatted notes (with the frontmatter convention below) are present. Without knowledge notes, they return empty results.
-
-Config location for Claude Desktop:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-## Claude Code Plugin
-
-The `claude-plugin/` directory contains a ready-to-use Claude Code plugin:
-
-```
-claude-plugin/
-├── .claude-plugin/
-│   └── plugin.json      # Plugin manifest
-├── .mcp.json            # MCP server definition (uses npx minimem mcp)
-├── skills/
-│   └── memory/
-│       └── SKILL.md     # Auto-invoked memory skill
-└── commands/
-    ├── remember.md      # /minimem:remember command
-    └── recall.md        # /minimem:recall command
-```
-
-### Testing the Plugin
-
-```bash
-claude --plugin-dir ./claude-plugin
-```
-
-### Plugin Commands
-
-- `/minimem:remember <text>` - Store information in memory
-- `/minimem:recall <query>` - Search for stored memories
-
-## Knowledge Frontmatter Convention
-
-minimem can index structured knowledge notes produced by external systems (e.g., cognitive-core). This is a **file-format convention only** — minimem does not import or depend on any external package.
-
-When a memory file's YAML frontmatter contains knowledge-specific fields, minimem parses them and populates metadata columns in the `chunks` table and edges in the `knowledge_links` table.
-
-### Supported fields
-
-All fields are optional. If absent, the file is treated as a regular memory note.
-
-```yaml
----
-id: k-abc123                     # Unique knowledge node ID
-type: observation                # observation | entity | domain-summary
-domain: [database, devops]       # Domain tags
-entities: [prisma, postgres]     # Referenced entities
-confidence: 0.85                 # Confidence score (0.0–1.0)
-source:                          # Provenance metadata
-  origin: extracted              # extracted | agent-authored
-  trajectories: [t-001, t-002]  # Source trajectory IDs
-  agentId: agent-v1             # Authoring agent
-links:                           # Graph edges to other knowledge nodes
-  - target: k-other
-    relation: related-to         # related-to | depends-on | supports | etc.
-    layer: semantic              # semantic | temporal | causal | entity
-  - target: k-dep
-    relation: depends-on
-created: 2025-01-15T10:00:00Z
-updated: 2025-01-15T12:00:00Z
-supersedes: k-old                # ID of note this replaces
-tags: [migration, patterns]
----
-# Note Title
-
-Body content in Markdown.
-```
-
-### How it works
-
-1. **Indexing** (`indexFile()`): When a file is indexed, frontmatter is parsed via `parseFrontmatter()`. If `type` is present, the chunk row gets `knowledge_type`, `knowledge_id`, `domains` (JSON), `entities` (JSON), and `confidence` populated. If `links` is present, rows are upserted into `knowledge_links`.
-
-2. **Filtered search** (`knowledgeSearch()`): Accepts `domain`, `entities`, `minConfidence`, and `knowledgeType` filters. Uses `json_each()` SQL for array column matching. Falls back to regular search when no filters are provided.
-
-3. **Graph traversal** (`src/search/graph.ts`): Operates on the `knowledge_links` table. Supports outgoing/incoming edge queries, BFS neighbor discovery (configurable depth), and shortest-path finding.
-
-4. **Re-indexing**: When a file changes, old `knowledge_links` for that file are deleted before new ones are inserted, keeping the graph consistent.
-
-### Independence guarantee
-
-- minimem defines its own types (`KnowledgeSource`, `KnowledgeLink`, `MemoryFrontmatter`) locally in `src/session.ts`
-- Zero imports from cognitive-core or any external knowledge system
-- All knowledge columns are nullable — regular memory files index without them
-- The `knowledge_links` table only gets rows when frontmatter contains `links`
-- All knowledge MCP tools (`knowledge_search`, `knowledge_graph`, `knowledge_path`) are additive alongside existing tools
-
-### Database schema (v4)
-
-Knowledge-related additions to the schema:
-
-```sql
--- Added columns on chunks table (all nullable)
-knowledge_type TEXT      -- 'observation', 'entity', 'domain-summary'
-knowledge_id TEXT        -- Note ID from frontmatter
-domains TEXT             -- JSON array of domain strings
-entities TEXT            -- JSON array of entity strings
-confidence REAL          -- 0.0–1.0
-
--- New table for graph edges
-CREATE TABLE knowledge_links (
-  from_id TEXT NOT NULL,
-  to_id TEXT NOT NULL,
-  relation TEXT NOT NULL,
-  layer TEXT,                     -- semantic, temporal, causal, entity
-  weight REAL DEFAULT 0.5,
-  source_path TEXT,
-  created_at INTEGER DEFAULT (unixepoch()),
-  PRIMARY KEY (from_id, to_id, relation)
-);
-```
-
-## Code Style
-
-- TypeScript with strict mode
-- ESM modules (no CommonJS)
-- Async/await for all I/O
-- Types exported alongside implementations
-- Tests use Node.js native test runner (not vitest) for integration tests