n2-soul 6.1.3 → 6.1.5

package/.gitattributes

@@ -0,0 +1,13 @@
+# Normalize line endings to LF on commit
+* text=auto eol=lf
+
+# Ensure these are always LF
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.n2 text eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.ico binary

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

@@ -39,16 +39,76 @@ 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/soul/index.js"]
+      "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/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/index.js

@@ -15,9 +15,10 @@ const { registerEndSequence } = require('./sequences/end');
 const { registerBrainTools } = require('./tools/brain');
 const { registerKVCacheTools } = require('./tools/kv-cache');
 
+const pkg = require('./package.json');
 const server = new McpServer({
     name: 'n2-soul',
-    version: '6.1.1',
+    version: pkg.version,
 });
 
 // ═══════════════════════════════════════════════════════
@@ -29,9 +30,10 @@ const server = new McpServer({
 // The RULES decide what's blocked — not the code.
 // ═══════════════════════════════════════════════════════
 const ark = createArk({
-    rulesDir: config.ARK?.rulesDir || path.join(__dirname, 'rules'),
-    auditDir: config.ARK?.auditDir || path.join(config.DATA_DIR, 'ark-audit'),
-    strictMode: config.ARK?.strictMode || false,
+    rulesDir: config.ARK?.rulesDir ?? path.join(__dirname, 'rules'),
+    auditDir: config.ARK?.auditDir ?? path.join(config.DATA_DIR, 'ark-audit'),
+    strictMode: config.ARK?.strictMode ?? false,
+    auditMaxAgeDays: config.ARK?.auditMaxAgeDays ?? 7,
     auditEnabled: true,
 });
 

package/lib/ark/index.js

@@ -23,16 +23,16 @@ function createArk(options = {}) {
     // Load and parse all .n2 rule files
     const rules = loadRules(rulesDir);
 
-    // Create audit logger
     const audit = new AuditLogger({
         dir: auditDir,
         enabled: options.auditEnabled !== false,
-        logPasses: options.auditPasses || false,
+        logPasses: options.auditPasses ?? false,
+        maxAgeDays: options.auditMaxAgeDays ?? 7,
     });
 
     // Create safety gate with audit hooks
     const gate = new SafetyGate(rules, {
-        strictMode: options.strictMode || false,
+        strictMode: options.strictMode ?? false,
         onBlock: (result) => audit.log(result, { type: result.type }),
         onPass: (result) => audit.log(result, { type: result.type }),
     });

package/lib/ark/parser.js

@@ -193,26 +193,56 @@ function extractPatterns(body) {
  */
 function parseGates(source) {
     const gates = {};
-    const gateRegex = /@gate\s+(\w+)\s*\{([^}]*)\}/g;
-    let match;
+    const lines = source.split('\n');
 
-    while ((match = gateRegex.exec(source)) !== null) {
-        const name = match[1];
-        const body = match[2];
+    let inGate = false;
+    let gateName = '';
+    let braceDepth = 0;
+    let bodyLines = [];
 
-        const actionsMatch = body.match(/actions\s*:\s*\[([^\]]+)\]/);
-        const actions = actionsMatch
-            ? actionsMatch[1].split(',').map(a => a.trim().replace(/["']/g, ''))
-            : [];
+    for (const line of lines) {
+        const trimmed = line.trim();
 
-        const requiresMatch = body.match(/requires\s*:\s*(\w+)/);
-        const requires = requiresMatch ? requiresMatch[1] : 'human_approval';
+        if (!inGate) {
+            const m = trimmed.match(/^@gate\s+(\w+)\s*\{?/);
+            if (m) {
+                inGate = true;
+                gateName = m[1];
+                braceDepth = (trimmed.includes('{')) ? 1 : 0;
+                bodyLines = [];
+                continue;
+            }
+        }
 
-        const minMatch = body.match(/min_approval_level\s*:\s*(\d+)/);
-        const minApproval = minMatch ? parseInt(minMatch[1], 10) : 1;
+        if (inGate) {
+            bodyLines.push(line);
+            for (const ch of line) {
+                if (ch === '{') braceDepth++;
+                if (ch === '}') braceDepth--;
+            }
 
-        if (actions.length > 0) {
-            gates[name] = { actions, requires, minApproval };
+            if (braceDepth <= 0) {
+                const body = bodyLines.join('\n');
+
+                const actionsMatch = body.match(/actions\s*:\s*\[([^\]]+)\]/);
+                const actions = actionsMatch
+                    ? actionsMatch[1].split(',').map(a => a.trim().replace(/["']/g, ''))
+                    : [];
+
+                const requiresMatch = body.match(/requires\s*:\s*(\w+)/);
+                const requires = requiresMatch ? requiresMatch[1] : 'human_approval';
+
+                const minMatch = body.match(/min_approval_level\s*:\s*(\d+)/);
+                const minApproval = minMatch ? parseInt(minMatch[1], 10) : 1;
+
+                if (actions.length > 0) {
+                    gates[gateName] = { actions, requires, minApproval };
+                }
+
+                inGate = false;
+                gateName = '';
+                bodyLines = [];
+            }
         }
     }
 

package/lib/config.default.js

@@ -37,6 +37,12 @@ module.exports = {
         childLimit: 20,
     },
 
+    // Work sequence settings
+    WORK: {
+        sessionTtlHours: 24,       // Auto-expire stale work sessions
+        maxDecisions: 20,          // Max decisions kept on soul-board
+    },
+
     // KV-Cache settings
     KV_CACHE: {
         enabled: true,
@@ -77,5 +83,6 @@ module.exports = {
         rulesDir: null,     // null = soul/rules/
         auditDir: null,     // null = soul/data/ark-audit/
         strictMode: false,  // true = block unknown actions too
+        auditMaxAgeDays: 7, // Auto-cleanup audit logs after N days
     },
 };

package/lib/intercom-log.js

@@ -51,7 +51,7 @@ function normalizeName(name) {
 // ── Path helpers ──
 
 function getConversationsDir(config) {
-    const dataDir = config?.dataDir || path.join(__dirname, '..', 'data');
+    const dataDir = config?.dataDir || config?.DATA_DIR || path.join(__dirname, '..', 'data');
     return path.join(dataDir, 'conversations');
 }
 

package/lib/paths.js

@@ -1,16 +1,23 @@
 // Soul MCP v6.0 — Central path manager. Cross-platform compatible.
-// NOTE: DATA_ROOT here is a fallback for agent-registry only.
-// For Cloud Storage, use config.DATA_DIR (set in config.local.js).
 const path = require('path');
 const fs = require('fs');
 
 // soul/lib/paths.js → 2 levels up = project root
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+// Local fallback only — always use config.DATA_DIR when available
 const DATA_ROOT = path.join(path.resolve(__dirname, '..'), 'data');
 
 /** Agents directory path (auto-created if needed) */
 function getAgentsDir() {
-    const dir = path.join(DATA_ROOT, 'agents');
+    // Prefer config.DATA_DIR (supports Cloud Storage) over local fallback
+    let dataDir;
+    try {
+        const config = require('./config');
+        dataDir = config.DATA_DIR || DATA_ROOT;
+    } catch (e) {
+        dataDir = DATA_ROOT;
+    }
+    const dir = path.join(dataDir, 'agents');
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     return dir;
 }

package/lib/utils.js

@@ -1,109 +1,120 @@
-// Soul MCP v6.0 — Shared utility functions (file I/O, time, security, logging)
-const fs = require('fs');
-const path = require('path');
-
-// Timezone: configurable via N2_TIMEZONE env or config.TIMEZONE
-const _tz = process.env.N2_TIMEZONE || 'Asia/Seoul';
-
-// -- 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: _tz });
-}
-
-function nowISO() {
-    const formatter = new Intl.DateTimeFormat('sv-SE', {
-        timeZone: _tz,
-        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: _tz });
-    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.3",
+    "version": "6.1.5",
     "description": "Multi-agent session orchestrator with KV-Cache and Ark for MCP (Model Context Protocol)",
     "main": "index.js",
     "scripts": {

package/sequences/boot.js

@@ -1,5 +1,6 @@
-// Soul MCP v6.0 — Boot sequence. Handoff + Entity/Core Memory injection + KV-Cache restore.
+// Soul MCP — Boot sequence. Handoff + Entity/Core Memory injection + KV-Cache restore.
 const path = require('path');
+const pkg = require('../package.json');
 const fs = require('fs');
 const { readJson, today, nowISO, logError } = require('../lib/utils');
 const { detectAgentsDir, listAgents } = require('../lib/agent-registry');
@@ -32,7 +33,7 @@ function registerBootSequence(server, z, config) {
             const agentName = agent || process.env.N2_AGENT_NAME || 'default';
             setAgentName(agentName);
 
-            lines.push(`--- Soul Boot v6.0 | ${agentName} | ${today()} ---`);
+            lines.push(`--- Soul Boot v${pkg.version} | ${agentName} | ${today()} ---`);
             if (agents.length > 0) {
                 lines.push(`Agents: ${agents.map(a => `${a.name}[${a.model}]`).join(', ')}`);
             }
@@ -114,7 +115,7 @@ function registerBootSequence(server, z, config) {
                 lines.push(`⚠️ Core Memory: ${e.message}`);
             }
 
-            lines.push(`\n--- Soul Boot v6.0 complete ---`);
+            lines.push(`\n--- Soul Boot v${pkg.version} complete ---`);
             return { content: [{ type: 'text', text: lines.join('\n') }] };
         }
     );

package/sequences/end.js

@@ -66,8 +66,8 @@ function registerEndSequence(server, z, config) {
                 for (const d of allDecisions) {
                     board.decisions.push({ date: dateStr, by: agent, what: d, why: '' });
                 }
-                if (board.decisions.length > 20) {
-                    board.decisions = board.decisions.slice(-20);
+                if (board.decisions.length > (config.WORK?.maxDecisions ?? 20)) {
+                    board.decisions = board.decisions.slice(-(config.WORK?.maxDecisions ?? 20));
                 }
 
                 board.updatedBy = agent;