n2-soul 6.1.4 → 6.1.6

package/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# Soul MCP — Funding configuration
+# This enables the 💖 Sponsor button on the GitHub repository
+github: [choihyunsus]

package/README.ko.md

@@ -31,24 +31,90 @@ Cursor, VS Code Copilot 등 MCP 호환 AI 에이전트와 새 채팅을 시작
 
 ### 1. 설치
 
+**방법 A: npm (권장)**
 ```bash
-git clone https://github.com/user/soul.git
+npm install n2-soul
+```
+
+**방법 B: 소스에서 설치**
+```bash
+git clone https://github.com/choihyunsus/soul.git
 cd soul
 npm install
 ```
 
 ### 2. MCP 설정에 Soul 추가
 
+Soul은 표준 MCP 서버(stdio)입니다. 사용 중인 호스트의 설정에 추가하세요:
+
+<details>
+<summary><strong>Cursor / VS Code Copilot / Claude Desktop</strong></summary>
+
+`mcp.json`, `settings.json`, 또는 `claude_desktop_config.json`에 추가:
+```json
+{
+  "mcpServers": {
+    "soul": {
+      "command": "node",
+      "args": ["/path/to/node_modules/n2-soul/index.js"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>🦙 Ollama + Open WebUI</strong></summary>
+
+Open WebUI는 MCP 도구를 네이티브로 지원합니다.
+
+```bash
+# 1. Ollama 실행 확인
+ollama serve
+
+# 2. Soul 설치
+npm install n2-soul
+
+# 3. Soul 경로 확인
+# Windows:
+echo %cd%\node_modules\n2-soul\index.js
+# Mac/Linux:
+echo $(pwd)/node_modules/n2-soul/index.js
+```
+
+**Open WebUI**에서: **⚙️ 설정 → Tools → MCP Servers** → 새 서버 추가:
+```
+Name:    soul
+Command: node
+Args:    /your/path/to/node_modules/n2-soul/index.js
+```
+
+이제 Open WebUI에서 채팅하는 모든 모델이 Soul의 20개 이상의 메모리 도구를 사용할 수 있습니다.
+</details>
+
+<details>
+<summary><strong>🖥️ LM Studio</strong></summary>
+
+LM Studio는 MCP를 네이티브로 지원합니다. `~/.lmstudio/mcp.json`에 추가:
 ```json
 {
   "mcpServers": {
     "soul": {
       "command": "node",
-      "args": ["/path/to/soul/index.js"]
+      "args": ["/path/to/node_modules/n2-soul/index.js"]
     }
   }
 }
 ```
+</details>
+
+<details>
+<summary><strong>🔧 기타 MCP 호환 호스트</strong></summary>
+
+Soul은 **stdio** 위의 표준 MCP 프로토콜을 사용합니다. MCP를 지원하는 도구라면 Soul이 작동합니다. command를 `node`로, args를 `n2-soul/index.js` 경로로 지정하면 됩니다.
+</details>
+
+> **💡 팁:** npm으로 설치한 경우 경로는 `node_modules/n2-soul/index.js`입니다. 소스에서 설치한 경우 클론한 디렉토리의 절대 경로를 사용하세요.
 
 ### 3. 에이전트에게 Soul 사용법 알려주기
 

package/README.md

@@ -66,16 +66,74 @@ npm install
 
 ### 2. Add Soul to your MCP config
 
+Soul is a standard MCP server (stdio). Add it to your host's config:
+
+<details>
+<summary><strong>Cursor / VS Code Copilot / Claude Desktop</strong></summary>
+
+Add to `mcp.json`, `settings.json`, or `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
     "soul": {
       "command": "node",
-      "args": ["/path/to/soul/index.js"]
+      "args": ["/path/to/node_modules/n2-soul/index.js"]
     }
   }
 }
 ```
+</details>
+
+<details>
+<summary><strong>🦙 Ollama + Open WebUI</strong></summary>
+
+Open WebUI supports MCP tools natively.
+
+```bash
+# 1. Make sure Ollama is running
+ollama serve
+
+# 2. Install Soul
+npm install n2-soul
+
+# 3. Find your Soul path
+# Windows:
+echo %cd%\node_modules\n2-soul\index.js
+# Mac/Linux:
+echo $(pwd)/node_modules/n2-soul/index.js
+```
+
+In **Open WebUI**: Go to **⚙️ Settings → Tools → MCP Servers** → Add new server:
+```
+Name:    soul
+Command: node
+Args:    /your/path/to/node_modules/n2-soul/index.js
+```
+
+Now any model you chat with in Open WebUI can use Soul's 20+ memory tools.
+</details>
+
+<details>
+<summary><strong>🖥️ LM Studio</strong></summary>
+
+LM Studio supports MCP natively. Add to `~/.lmstudio/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "soul": {
+      "command": "node",
+      "args": ["/path/to/node_modules/n2-soul/index.js"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>🔧 Any other MCP-compatible host</strong></summary>
+
+Soul speaks standard MCP protocol over **stdio**. If your tool supports MCP, Soul works. Just point the command to `node` and the args to `n2-soul/index.js`.
+</details>
 
 > **💡 Tip:** If you installed via npm, the path is `node_modules/n2-soul/index.js`. If from source, use the absolute path to your cloned directory.
 

package/lib/utils.js

@@ -1,120 +1,120 @@
-// Soul MCP v6.0 — Shared utility functions (file I/O, time, security, logging)
-const fs = require('fs');
-const path = require('path');
-
-// Timezone: prioritizes env > config.TIMEZONE > fallback 'Asia/Seoul'
-let _tz = null;
-function _getTimezone() {
-    if (!_tz) {
-        try {
-            const config = require('./config');
-            _tz = process.env.N2_TIMEZONE || config.TIMEZONE || 'Asia/Seoul';
-        } catch (e) {
-            _tz = process.env.N2_TIMEZONE || 'Asia/Seoul';
-        }
-    }
-    return _tz;
-}
-
-// -- Logging --
-
-function logError(context, err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[soul:${context}]`, msg);
-}
-
-// -- File I/O --
-
-function readFile(filePath) {
-    try {
-        return fs.readFileSync(filePath, 'utf8');
-    } catch (e) {
-        logError('readFile', e);
-        return null;
-    }
-}
-
-function readJson(filePath) {
-    const content = readFile(filePath);
-    if (!content) return null;
-    try {
-        return JSON.parse(content);
-    } catch (e) {
-        logError('readJson', e);
-        return null;
-    }
-}
-
-function writeJson(filePath, data) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
-}
-
-function writeFile(filePath, content) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, content, 'utf8');
-}
-
-// -- Time --
-
-function today() {
-    return new Date().toLocaleDateString('sv-SE', { timeZone: _getTimezone() });
-}
-
-function nowISO() {
-    const formatter = new Intl.DateTimeFormat('sv-SE', {
-        timeZone: _getTimezone(),
-        year: 'numeric', month: '2-digit', day: '2-digit',
-        hour: '2-digit', minute: '2-digit', second: '2-digit',
-        hour12: false,
-    });
-    const parts = formatter.formatToParts(new Date());
-    const get = (type) => parts.find(p => p.type === type)?.value || '00';
-    // Compute UTC offset dynamically for the configured timezone
-    const now = new Date();
-    const utcStr = now.toLocaleString('en-US', { timeZone: 'UTC' });
-    const tzStr = now.toLocaleString('en-US', { timeZone: _getTimezone() });
-    const diffMs = new Date(tzStr) - new Date(utcStr);
-    const diffH = Math.floor(Math.abs(diffMs) / 3600000);
-    const diffM = Math.floor((Math.abs(diffMs) % 3600000) / 60000);
-    const sign = diffMs >= 0 ? '+' : '-';
-    const offset = `${sign}${String(diffH).padStart(2, '0')}:${String(diffM).padStart(2, '0')}`;
-    return `${get('year')}-${get('month')}-${get('day')}T${get('hour')}:${get('minute')}:${get('second')}${offset}`;
-}
-
-// -- Security --
-
-function safePath(filePath, baseDir) {
-    const resolved = path.resolve(baseDir, filePath);
-    const normalizedBase = path.resolve(baseDir);
-    if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
-        logError('safePath', `Path traversal blocked: ${filePath}`);
-        return null;
-    }
-    return resolved;
-}
-
-// -- First-line comment validation --
-
-function validateFirstLineComment(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf8');
-        const firstLine = content.split('\n')[0].trim();
-        const patterns = [
-            /^\/\/\s*.+/,     // JS/TS
-            /^#\s*.+/,        // Python/Shell/YAML
-            /^<!--\s*.+/,     // HTML/MD
-            /^\/\*\s*.+/,     // CSS/Java
-            /^\{.*"_desc"/,   // JSON with _desc field
-        ];
-        return patterns.some(p => p.test(firstLine));
-    } catch (e) {
-        logError('validateFirstLineComment', e);
-        return false;
-    }
-}
-
-module.exports = {
-    logError, readFile, readJson, writeJson, writeFile,
-    today, nowISO, safePath, validateFirstLineComment,
-};
+// Soul MCP v6.0 — Shared utility functions (file I/O, time, security, logging)
+const fs = require('fs');
+const path = require('path');
+
+// Timezone: prioritizes env > config.TIMEZONE > fallback 'Asia/Seoul'
+let _tz = null;
+function _getTimezone() {
+    if (!_tz) {
+        try {
+            const config = require('./config');
+            _tz = process.env.N2_TIMEZONE || config.TIMEZONE || 'Asia/Seoul';
+        } catch (e) {
+            _tz = process.env.N2_TIMEZONE || 'Asia/Seoul';
+        }
+    }
+    return _tz;
+}
+
+// -- Logging --
+
+function logError(context, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[soul:${context}]`, msg);
+}
+
+// -- File I/O --
+
+function readFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+        logError('readFile', e);
+        return null;
+    }
+}
+
+function readJson(filePath) {
+    const content = readFile(filePath);
+    if (!content) return null;
+    try {
+        return JSON.parse(content);
+    } catch (e) {
+        logError('readJson', e);
+        return null;
+    }
+}
+
+function writeJson(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+}
+
+// -- Time --
+
+function today() {
+    return new Date().toLocaleDateString('sv-SE', { timeZone: _getTimezone() });
+}
+
+function nowISO() {
+    const formatter = new Intl.DateTimeFormat('sv-SE', {
+        timeZone: _getTimezone(),
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit',
+        hour12: false,
+    });
+    const parts = formatter.formatToParts(new Date());
+    const get = (type) => parts.find(p => p.type === type)?.value || '00';
+    // Compute UTC offset dynamically for the configured timezone
+    const now = new Date();
+    const utcStr = now.toLocaleString('en-US', { timeZone: 'UTC' });
+    const tzStr = now.toLocaleString('en-US', { timeZone: _getTimezone() });
+    const diffMs = new Date(tzStr) - new Date(utcStr);
+    const diffH = Math.floor(Math.abs(diffMs) / 3600000);
+    const diffM = Math.floor((Math.abs(diffMs) % 3600000) / 60000);
+    const sign = diffMs >= 0 ? '+' : '-';
+    const offset = `${sign}${String(diffH).padStart(2, '0')}:${String(diffM).padStart(2, '0')}`;
+    return `${get('year')}-${get('month')}-${get('day')}T${get('hour')}:${get('minute')}:${get('second')}${offset}`;
+}
+
+// -- Security --
+
+function safePath(filePath, baseDir) {
+    const resolved = path.resolve(baseDir, filePath);
+    const normalizedBase = path.resolve(baseDir);
+    if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+        logError('safePath', `Path traversal blocked: ${filePath}`);
+        return null;
+    }
+    return resolved;
+}
+
+// -- First-line comment validation --
+
+function validateFirstLineComment(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const firstLine = content.split('\n')[0].trim();
+        const patterns = [
+            /^\/\/\s*.+/,     // JS/TS
+            /^#\s*.+/,        // Python/Shell/YAML
+            /^<!--\s*.+/,     // HTML/MD
+            /^\/\*\s*.+/,     // CSS/Java
+            /^\{.*"_desc"/,   // JSON with _desc field
+        ];
+        return patterns.some(p => p.test(firstLine));
+    } catch (e) {
+        logError('validateFirstLineComment', e);
+        return false;
+    }
+}
+
+module.exports = {
+    logError, readFile, readJson, writeJson, writeFile,
+    today, nowISO, safePath, validateFirstLineComment,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "n2-soul",
-    "version": "6.1.4",
+    "version": "6.1.6",
     "description": "Multi-agent session orchestrator with KV-Cache and Ark for MCP (Model Context Protocol)",
     "main": "index.js",
     "scripts": {

package/sequences/work.js

@@ -1,271 +1,271 @@
-// Soul MCP v6.0 — Work sequence. Real-time change tracking, file ownership, context search.
-const fs = require('fs');
-const path = require('path');
-const { nowISO, readJson, readFile, validateFirstLineComment, logError } = require('../lib/utils');
-const { SoulEngine } = require('../lib/soul-engine');
-
-// In-memory work session state per project
-const activeSessions = {};
-
-// TTL: auto-expire stale sessions (checked every hour)
-const SESSION_TTL_MS = (require('../lib/config').WORK?.sessionTtlHours ?? 24) * 60 * 60 * 1000;
-const _sessionGcTimer = setInterval(() => {
-    const now = Date.now();
-    for (const [project, session] of Object.entries(activeSessions)) {
-        if (session._createdMs && (now - session._createdMs) > SESSION_TTL_MS) {
-            delete activeSessions[project];
-            logError('work:ttl', `Expired stale session: ${project} (agent: ${session.agent})`);
-        }
-    }
-}, 60 * 60 * 1000);
-_sessionGcTimer.unref(); // Don't prevent Node.js from exiting
-
-// ── Helper: recursively walk files in a directory ──
-function walkFiles(dir, callback, maxDepth, depth = 0) {
-    if (depth > maxDepth) return;
-    try {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walkFiles(fullPath, callback, maxDepth, depth + 1);
-            } else {
-                callback(fullPath);
-            }
-        }
-    } catch (e) {
-        logError("walkFiles", `${dir}: ${e.message}`);
-    }
-}
-
-function registerWorkSequence(server, z, config) {
-    const engine = new SoulEngine(config.DATA_DIR);
-
-    // Start a work sequence
-    server.registerTool(
-        'n2_work_start',
-        {
-            title: 'N2 Work Start',
-            description: 'Start a work sequence. Registers agent in activeWork on soul-board.',
-            inputSchema: {
-                agent: z.string().describe('Agent name'),
-                project: z.string().describe('Project name'),
-                task: z.string().describe('Task description'),
-            },
-        },
-        async ({ agent, project, task }) => {
-            engine.setActiveWork(project, agent, task, []);
-            activeSessions[project] = {
-                agent,
-                task,
-                startedAt: nowISO(),
-                _createdMs: Date.now(),
-                filesCreated: [],
-                filesModified: [],
-                filesDeleted: [],
-                decisions: [],
-            };
-            return { content: [{ type: 'text', text: `Work started: ${agent} on ${project} — ${task}` }] };
-        }
-    );
-
-    // Claim file ownership before editing
-    server.registerTool(
-        'n2_work_claim',
-        {
-            title: 'N2 Work Claim',
-            description: 'Claim file ownership before modifying. Prevents collision with other agents.',
-            inputSchema: {
-                project: z.string().describe('Project name'),
-                agent: z.string().describe('Agent name'),
-                filePath: z.string().describe('File path relative to project root'),
-                intent: z.string().describe('Why you are modifying this file'),
-            },
-        },
-        async ({ project, agent, filePath, intent }) => {
-            const result = engine.claimFile(project, filePath, agent, intent);
-            if (!result.ok) {
-                return { content: [{ type: 'text', text: `COLLISION: ${filePath} is owned by ${result.owner} (${result.intent}). Choose a different file.` }] };
-            }
-            return { content: [{ type: 'text', text: `Claimed: ${filePath} -> ${agent} (${intent})` }] };
-        }
-    );
-
-    // Log file changes during work
-    server.registerTool(
-        'n2_work_log',
-        {
-            title: 'N2 Work Log',
-            description: 'Log file changes during work. Reports created/modified/deleted files with descriptions.',
-            inputSchema: {
-                project: z.string().describe('Project name'),
-                filesCreated: z.array(z.object({
-                    path: z.string(),
-                    desc: z.string(),
-                })).optional().describe('Files created'),
-                filesModified: z.array(z.object({
-                    path: z.string(),
-                    desc: z.string(),
-                })).optional().describe('Files modified'),
-                filesDeleted: z.array(z.object({
-                    path: z.string(),
-                    desc: z.string(),
-                })).optional().describe('Files deleted'),
-                decisions: z.array(z.string()).optional().describe('Decisions made'),
-            },
-        },
-        async ({ project, filesCreated, filesModified, filesDeleted, decisions }) => {
-            const session = activeSessions[project];
-            if (!session) {
-                return { content: [{ type: 'text', text: 'ERROR: No active work session. Call n2_work_start first.' }] };
-            }
-
-            if (filesCreated) session.filesCreated.push(...filesCreated);
-            if (filesModified) session.filesModified.push(...filesModified);
-            if (filesDeleted) session.filesDeleted.push(...filesDeleted);
-            if (decisions) session.decisions.push(...decisions);
-
-            // Validate first-line comments on created files
-            const warnings = [];
-            for (const f of (filesCreated || [])) {
-                try {
-                    const fullPath = path.resolve(f.path);
-                    if (!validateFirstLineComment(fullPath)) {
-                        warnings.push(`MISSING first-line comment: ${f.path}`);
-                    }
-                } catch (e) { logError("work:validate", e); }
-            }
-
-            const total = (session.filesCreated.length + session.filesModified.length + session.filesDeleted.length);
-            let msg = `Logged: ${total} file changes, ${session.decisions.length} decisions.`;
-            if (warnings.length > 0) {
-                msg += `\nWARNINGS:\n  ${warnings.join('\n  ')}`;
-            }
-            if ((filesCreated && filesCreated.length > 0) || (filesDeleted && filesDeleted.length > 0)) {
-                msg += `\nFile tree will auto-update at n2_work_end. Use n2_project_scan for immediate refresh.`;
-            }
-            msg += `\nTODO RULE: All TODO files go in _data/ ONLY. Always mark completed items as [x]. Never use brain memory for TODOs.`;
-            return { content: [{ type: 'text', text: msg }] };
-        }
-    );
-
-    // ── n2_context_search: Search across Brain memory and Ledger entries ──
-    server.registerTool(
-        'n2_context_search',
-        {
-            title: 'N2 Context Search',
-            description: 'Search across Brain memory and Ledger entries for relevant past context. Uses keyword matching with recency weighting. Great for finding related past work or decisions.',
-            inputSchema: {
-                query: z.string().describe('Search query (keywords, space-separated)'),
-                sources: z.array(z.string()).optional().describe('Sources to search: "brain", "ledger". Default: all.'),
-                maxResults: z.number().optional().describe('Max results (default: 10)'),
-            },
-        },
-        async ({ query, sources, maxResults }) => {
-            try {
-                const dataDir = config.DATA_DIR;
-                const searchCfg = config.SEARCH || {};
-                const minKwLen = searchCfg.minKeywordLength || 2;
-                const previewLen = searchCfg.previewLength || 200;
-                const recencyBonus = searchCfg.recencyBonus || 10;
-                const maxDepth = searchCfg.maxDepth || 6;
-                const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length >= minKwLen);
-                const max = maxResults || searchCfg.defaultMaxResults || 10;
-                const searchSources = sources || ['brain', 'ledger'];
-                const results = [];
-
-                function scoreText(text, filePath, source, meta = {}) {
-                    if (!text) return;
-                    const lower = text.toLowerCase();
-                    let score = 0;
-                    const matchedKeywords = [];
-                    for (const kw of keywords) {
-                        const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-                        const count = (lower.match(new RegExp(escaped, 'g')) || []).length;
-                        if (count > 0) { score += count; matchedKeywords.push(kw); }
-                    }
-                    if (score > 0) {
-                        if (meta.timestamp) {
-                            const age = (Date.now() - new Date(meta.timestamp).getTime()) / (1000 * 60 * 60 * 24);
-                            score += Math.max(0, recencyBonus - age);
-                        }
-                        results.push({
-                            source, path: filePath,
-                            score: Math.round(score * 100) / 100,
-                            matchedKeywords,
-                            preview: text.slice(0, previewLen).replace(/\n/g, ' '),
-                            ...meta,
-                        });
-                    }
-                }
-
-                // Search Brain memory
-                if (searchSources.includes('brain')) {
-                    const memoryDir = path.join(dataDir, 'memory');
-                    if (fs.existsSync(memoryDir)) {
-                        walkFiles(memoryDir, (fp) => {
-                            const content = readFile(fp);
-                            if (content) {
-                                const relPath = path.relative(memoryDir, fp);
-                                scoreText(content, `memory/${relPath}`, 'brain', {
-                                    timestamp: fs.statSync(fp).mtime.toISOString(),
-                                });
-                            }
-                        }, maxDepth);
-                    }
-                }
-
-                // Search Ledger entries
-                if (searchSources.includes('ledger')) {
-                    const projectsDir = path.join(dataDir, 'projects');
-                    if (fs.existsSync(projectsDir)) {
-                        for (const proj of fs.readdirSync(projectsDir)) {
-                            const ledgerBase = path.join(projectsDir, proj, 'ledger');
-                            if (!fs.existsSync(ledgerBase)) continue;
-                            walkFiles(ledgerBase, (fp) => {
-                                if (!fp.endsWith('.json')) return;
-                                const data = readJson(fp);
-                                if (!data) return;
-                                const text = [data.title, data.summary, ...(data.decisions || [])].filter(Boolean).join(' ');
-                                const relPath = path.relative(projectsDir, fp);
-                                scoreText(text, `projects/${relPath}`, 'ledger', {
-                                    timestamp: data.completedAt || data.startedAt,
-                                    agent: data.agent,
-                                    title: data.title,
-                                });
-                            }, maxDepth);
-                        }
-                    }
-                }
-
-                results.sort((a, b) => b.score - a.score);
-                const top = results.slice(0, max);
-
-                if (top.length === 0) {
-                    return { content: [{ type: 'text', text: `🔍 No results for "${query}".` }] };
-                }
-
-                const lines = top.map((r, i) => {
-                    const icon = r.source === 'brain' ? '🧠' : '📖';
-                    const meta = [
-                        r.title ? `"${r.title}"` : '',
-                        r.agent ? `by ${r.agent}` : '',
-                        `score: ${r.score}`,
-                    ].filter(Boolean).join(' | ');
-                    return `${i + 1}. ${icon} ${r.path}\n   ${meta}\n   Keywords: [${r.matchedKeywords.join(', ')}]\n   ${r.preview}`;
-                });
-
-                return {
-                    content: [{
-                        type: 'text', text:
-                            `🔍 Context search: "${query}" (${top.length} results)\n\n${lines.join('\n\n')}`
-                    }],
-                };
-            } catch (err) {
-                return { content: [{ type: 'text', text: `❌ Search error: ${err.message}` }] };
-            }
-        }
-    );
-}
-
-// Export activeSessions for end.js to access
-module.exports = { registerWorkSequence, activeSessions };
+// Soul MCP v6.0 — Work sequence. Real-time change tracking, file ownership, context search.
+const fs = require('fs');
+const path = require('path');
+const { nowISO, readJson, readFile, validateFirstLineComment, logError } = require('../lib/utils');
+const { SoulEngine } = require('../lib/soul-engine');
+
+// In-memory work session state per project
+const activeSessions = {};
+
+// TTL: auto-expire stale sessions (checked every hour)
+const SESSION_TTL_MS = (require('../lib/config').WORK?.sessionTtlHours ?? 24) * 60 * 60 * 1000;
+const _sessionGcTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [project, session] of Object.entries(activeSessions)) {
+        if (session._createdMs && (now - session._createdMs) > SESSION_TTL_MS) {
+            delete activeSessions[project];
+            logError('work:ttl', `Expired stale session: ${project} (agent: ${session.agent})`);
+        }
+    }
+}, 60 * 60 * 1000);
+_sessionGcTimer.unref(); // Don't prevent Node.js from exiting
+
+// ── Helper: recursively walk files in a directory ──
+function walkFiles(dir, callback, maxDepth, depth = 0) {
+    if (depth > maxDepth) return;
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkFiles(fullPath, callback, maxDepth, depth + 1);
+            } else {
+                callback(fullPath);
+            }
+        }
+    } catch (e) {
+        logError("walkFiles", `${dir}: ${e.message}`);
+    }
+}
+
+function registerWorkSequence(server, z, config) {
+    const engine = new SoulEngine(config.DATA_DIR);
+
+    // Start a work sequence
+    server.registerTool(
+        'n2_work_start',
+        {
+            title: 'N2 Work Start',
+            description: 'Start a work sequence. Registers agent in activeWork on soul-board.',
+            inputSchema: {
+                agent: z.string().describe('Agent name'),
+                project: z.string().describe('Project name'),
+                task: z.string().describe('Task description'),
+            },
+        },
+        async ({ agent, project, task }) => {
+            engine.setActiveWork(project, agent, task, []);
+            activeSessions[project] = {
+                agent,
+                task,
+                startedAt: nowISO(),
+                _createdMs: Date.now(),
+                filesCreated: [],
+                filesModified: [],
+                filesDeleted: [],
+                decisions: [],
+            };
+            return { content: [{ type: 'text', text: `Work started: ${agent} on ${project} — ${task}` }] };
+        }
+    );
+
+    // Claim file ownership before editing
+    server.registerTool(
+        'n2_work_claim',
+        {
+            title: 'N2 Work Claim',
+            description: 'Claim file ownership before modifying. Prevents collision with other agents.',
+            inputSchema: {
+                project: z.string().describe('Project name'),
+                agent: z.string().describe('Agent name'),
+                filePath: z.string().describe('File path relative to project root'),
+                intent: z.string().describe('Why you are modifying this file'),
+            },
+        },
+        async ({ project, agent, filePath, intent }) => {
+            const result = engine.claimFile(project, filePath, agent, intent);
+            if (!result.ok) {
+                return { content: [{ type: 'text', text: `COLLISION: ${filePath} is owned by ${result.owner} (${result.intent}). Choose a different file.` }] };
+            }
+            return { content: [{ type: 'text', text: `Claimed: ${filePath} -> ${agent} (${intent})` }] };
+        }
+    );
+
+    // Log file changes during work
+    server.registerTool(
+        'n2_work_log',
+        {
+            title: 'N2 Work Log',
+            description: 'Log file changes during work. Reports created/modified/deleted files with descriptions.',
+            inputSchema: {
+                project: z.string().describe('Project name'),
+                filesCreated: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files created'),
+                filesModified: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files modified'),
+                filesDeleted: z.array(z.object({
+                    path: z.string(),
+                    desc: z.string(),
+                })).optional().describe('Files deleted'),
+                decisions: z.array(z.string()).optional().describe('Decisions made'),
+            },
+        },
+        async ({ project, filesCreated, filesModified, filesDeleted, decisions }) => {
+            const session = activeSessions[project];
+            if (!session) {
+                return { content: [{ type: 'text', text: 'ERROR: No active work session. Call n2_work_start first.' }] };
+            }
+
+            if (filesCreated) session.filesCreated.push(...filesCreated);
+            if (filesModified) session.filesModified.push(...filesModified);
+            if (filesDeleted) session.filesDeleted.push(...filesDeleted);
+            if (decisions) session.decisions.push(...decisions);
+
+            // Validate first-line comments on created files
+            const warnings = [];
+            for (const f of (filesCreated || [])) {
+                try {
+                    const fullPath = path.resolve(f.path);
+                    if (!validateFirstLineComment(fullPath)) {
+                        warnings.push(`MISSING first-line comment: ${f.path}`);
+                    }
+                } catch (e) { logError("work:validate", e); }
+            }
+
+            const total = (session.filesCreated.length + session.filesModified.length + session.filesDeleted.length);
+            let msg = `Logged: ${total} file changes, ${session.decisions.length} decisions.`;
+            if (warnings.length > 0) {
+                msg += `\nWARNINGS:\n  ${warnings.join('\n  ')}`;
+            }
+            if ((filesCreated && filesCreated.length > 0) || (filesDeleted && filesDeleted.length > 0)) {
+                msg += `\nFile tree will auto-update at n2_work_end. Use n2_project_scan for immediate refresh.`;
+            }
+            msg += `\nTODO RULE: All TODO files go in _data/ ONLY. Always mark completed items as [x]. Never use brain memory for TODOs.`;
+            return { content: [{ type: 'text', text: msg }] };
+        }
+    );
+
+    // ── n2_context_search: Search across Brain memory and Ledger entries ──
+    server.registerTool(
+        'n2_context_search',
+        {
+            title: 'N2 Context Search',
+            description: 'Search across Brain memory and Ledger entries for relevant past context. Uses keyword matching with recency weighting. Great for finding related past work or decisions.',
+            inputSchema: {
+                query: z.string().describe('Search query (keywords, space-separated)'),
+                sources: z.array(z.string()).optional().describe('Sources to search: "brain", "ledger". Default: all.'),
+                maxResults: z.number().optional().describe('Max results (default: 10)'),
+            },
+        },
+        async ({ query, sources, maxResults }) => {
+            try {
+                const dataDir = config.DATA_DIR;
+                const searchCfg = config.SEARCH || {};
+                const minKwLen = searchCfg.minKeywordLength || 2;
+                const previewLen = searchCfg.previewLength || 200;
+                const recencyBonus = searchCfg.recencyBonus || 10;
+                const maxDepth = searchCfg.maxDepth || 6;
+                const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length >= minKwLen);
+                const max = maxResults || searchCfg.defaultMaxResults || 10;
+                const searchSources = sources || ['brain', 'ledger'];
+                const results = [];
+
+                function scoreText(text, filePath, source, meta = {}) {
+                    if (!text) return;
+                    const lower = text.toLowerCase();
+                    let score = 0;
+                    const matchedKeywords = [];
+                    for (const kw of keywords) {
+                        const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        const count = (lower.match(new RegExp(escaped, 'g')) || []).length;
+                        if (count > 0) { score += count; matchedKeywords.push(kw); }
+                    }
+                    if (score > 0) {
+                        if (meta.timestamp) {
+                            const age = (Date.now() - new Date(meta.timestamp).getTime()) / (1000 * 60 * 60 * 24);
+                            score += Math.max(0, recencyBonus - age);
+                        }
+                        results.push({
+                            source, path: filePath,
+                            score: Math.round(score * 100) / 100,
+                            matchedKeywords,
+                            preview: text.slice(0, previewLen).replace(/\n/g, ' '),
+                            ...meta,
+                        });
+                    }
+                }
+
+                // Search Brain memory
+                if (searchSources.includes('brain')) {
+                    const memoryDir = path.join(dataDir, 'memory');
+                    if (fs.existsSync(memoryDir)) {
+                        walkFiles(memoryDir, (fp) => {
+                            const content = readFile(fp);
+                            if (content) {
+                                const relPath = path.relative(memoryDir, fp);
+                                scoreText(content, `memory/${relPath}`, 'brain', {
+                                    timestamp: fs.statSync(fp).mtime.toISOString(),
+                                });
+                            }
+                        }, maxDepth);
+                    }
+                }
+
+                // Search Ledger entries
+                if (searchSources.includes('ledger')) {
+                    const projectsDir = path.join(dataDir, 'projects');
+                    if (fs.existsSync(projectsDir)) {
+                        for (const proj of fs.readdirSync(projectsDir)) {
+                            const ledgerBase = path.join(projectsDir, proj, 'ledger');
+                            if (!fs.existsSync(ledgerBase)) continue;
+                            walkFiles(ledgerBase, (fp) => {
+                                if (!fp.endsWith('.json')) return;
+                                const data = readJson(fp);
+                                if (!data) return;
+                                const text = [data.title, data.summary, ...(data.decisions || [])].filter(Boolean).join(' ');
+                                const relPath = path.relative(projectsDir, fp);
+                                scoreText(text, `projects/${relPath}`, 'ledger', {
+                                    timestamp: data.completedAt || data.startedAt,
+                                    agent: data.agent,
+                                    title: data.title,
+                                });
+                            }, maxDepth);
+                        }
+                    }
+                }
+
+                results.sort((a, b) => b.score - a.score);
+                const top = results.slice(0, max);
+
+                if (top.length === 0) {
+                    return { content: [{ type: 'text', text: `🔍 No results for "${query}".` }] };
+                }
+
+                const lines = top.map((r, i) => {
+                    const icon = r.source === 'brain' ? '🧠' : '📖';
+                    const meta = [
+                        r.title ? `"${r.title}"` : '',
+                        r.agent ? `by ${r.agent}` : '',
+                        `score: ${r.score}`,
+                    ].filter(Boolean).join(' | ');
+                    return `${i + 1}. ${icon} ${r.path}\n   ${meta}\n   Keywords: [${r.matchedKeywords.join(', ')}]\n   ${r.preview}`;
+                });
+
+                return {
+                    content: [{
+                        type: 'text', text:
+                            `🔍 Context search: "${query}" (${top.length} results)\n\n${lines.join('\n\n')}`
+                    }],
+                };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `❌ Search error: ${err.message}` }] };
+            }
+        }
+    );
+}
+
+// Export activeSessions for end.js to access
+module.exports = { registerWorkSequence, activeSessions };