n2-soul 4.1.0

package/LICENSE

@@ -0,0 +1,121 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 N2
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.ko.md

@@ -0,0 +1,197 @@
+🇬🇧 [English](README.md)
+
+# 🧠 Soul
+
+**AI 에이전트는 세션이 끝나면 모든 걸 잊어버립니다. Soul이 그걸 해결합니다.**
+
+Cursor, VS Code Copilot 등 MCP 호환 AI 에이전트와 새 채팅을 시작할 때마다, 에이전트는 이전에 뭘 했는지 전혀 모른 채 처음부터 시작합니다. Soul은 에이전트에게 이런 능력을 부여하는 MCP 서버입니다:
+
+- 🧠 **영구 기억** — 세션이 끝나도 기억이 유지됩니다
+- 🤝 **인수인계** — 한 에이전트가 다른 에이전트의 작업을 이어받을 수 있습니다
+- 📝 **작업 이력** — 모든 작업이 변경 불가능한 로그로 기록됩니다
+- 🗂️ **공유 두뇌** — 여러 에이전트가 같은 컨텍스트를 읽고 쓸 수 있습니다
+
+> ⚡ **Soul은 N2 Browser의 작은 부속품 하나입니다** — 우리가 만들고 있는 AI 네이티브 브라우저의 일부예요. 멀티 에이전트 오케스트레이션, 실시간 도구 라우팅, 에이전트 간 통신 등 훨씬 더 많은 기능들이 현재 테스트 중입니다. 이건 시작에 불과합니다.
+
+## 빠른 시작
+
+### 1. 설치
+
+```bash
+git clone https://github.com/user/soul.git
+cd soul
+npm install
+```
+
+### 2. MCP 설정에 Soul 추가
+
+```json
+{
+  "mcpServers": {
+    "soul": {
+      "command": "node",
+      "args": ["/path/to/soul/index.js"]
+    }
+  }
+}
+```
+
+### 3. 에이전트에게 Soul 사용법 알려주기
+
+에이전트의 규칙 파일 (`.md`, `.cursorrules`, 시스템 프롬프트 등)에 이것만 추가하세요:
+
+```markdown
+## 세션 관리
+- 세션 시작 시 n2_boot를 에이전트 이름과 프로젝트 이름으로 호출하세요.
+- 세션 종료 시 n2_work_end를 요약과 TODO 목록과 함께 호출하세요.
+```
+
+끝입니다. **에이전트가 알아야 할 명령어 딱 2개:**
+
+| 명령어 | 타이밍 | 하는 일 |
+|--------|--------|--------|
+| `n2_boot(agent, project)` | 세션 시작 | 이전 컨텍스트, 인수인계, TODO 로드 |
+| `n2_work_end(agent, project, ...)` | 세션 종료 | 모든 것을 다음 세션을 위해 저장 |
+
+다음 세션에서 에이전트는 이전에 하던 작업을 정확히 이어서 합니다 — 마치 잊은 적이 없는 것처럼.
+
+### 실행 환경
+
+- Node.js 18+
+
+## 왜 Soul인가?
+
+| Soul 없이 | Soul 있으면 |
+|-----------|-----------|
+| 매 세션 처음부터 시작 | 에이전트가 지난번에 뭘 했는지 기억 |
+| 매번 컨텍스트 다시 설명 | 컨텍스트가 수 초 만에 자동 로드 |
+| 에이전트 A가 에이전트 B의 작업을 이어받지 못함 | 에이전트 간 매끄러운 인수인계 |
+| 두 에이전트가 같은 파일 수정 = 충돌 | 파일 소유권으로 충돌 방지 |
+| 긴 대화에서 요약 반복으로 토큰 낭비 | 필요한 만큼만 점진적 로딩 |
+
+## 작동 방식
+
+```
+세션 시작 → "Boot"
+    ↓
+n2_boot(agent, project)     → 인수인계 + KV-Cache 컨텍스트 로드
+    ↓
+n2_work_start(project, task) → 작업 시작 등록
+    ↓
+... 에이전트가 평소처럼 작업 ...
+n2_brain_read/write          → 공유 메모리
+n2_work_claim(file)          → 파일 충돌 방지
+n2_work_log(files)           → 변경 사항 추적
+    ↓
+세션 종료 → "End"
+    ↓
+n2_work_end(project, title, summary, todo)
+    ├→ 변경 불가능한 작업 기록 저장
+    ├→ 다음 에이전트를 위한 인수인계 업데이트
+    ├→ KV-Cache 스냅샷 자동 저장
+    └→ 파일 소유권 해제
+```
+
+## 기능
+
+| 기능 | 설명 |
+|------|------|
+| **Soul Board** | 프로젝트 상태 + TODO 추적 + 에이전트 간 인수인계 |
+| **불변 원장 (Ledger)** | 모든 작업 세션을 추가 전용 로그로 기록 |
+| **KV-Cache** | 세션 스냅샷 + 압축 + 계층형 저장 (Hot/Warm/Cold) |
+| **공유 두뇌 (Brain)** | 경로 순회 공격 방어가 포함된 파일 기반 공유 메모리 |
+| **컨텍스트 검색** | 두뇌 메모리와 원장을 키워드로 검색 |
+| **파일 소유권** | 여러 에이전트의 동시 파일 편집 충돌 방지 |
+| **듀얼 백엔드** | JSON (의존성 없음) 또는 SQLite (고성능) |
+| **시맨틱 검색** | Ollama 임베딩 연동 (nomic-embed-text, 선택사항) |
+| **백업/복원** | 설정 가능한 보존 기간의 증분 백업 |
+
+## 사용 가능한 도구
+
+| 도구 | 설명 |
+|------|------|
+| `n2_boot` | 부팅 — 인수인계, 에이전트, KV-Cache 로드 |
+| `n2_work_start` | 작업 세션 시작 등록 |
+| `n2_work_claim` | 파일 소유권 선점 (충돌 방지) |
+| `n2_work_log` | 작업 중 파일 변경 기록 |
+| `n2_work_end` | 세션 종료 — 원장, 인수인계, KV-Cache 저장 |
+| `n2_brain_read` | 공유 메모리 읽기 |
+| `n2_brain_write` | 공유 메모리 쓰기 |
+| `n2_context_search` | 두뇌 + 원장 전체 검색 |
+| `n2_kv_save` | KV-Cache 수동 저장 |
+| `n2_kv_load` | 최신 스냅샷 로드 |
+| `n2_kv_search` | 키워드로 과거 세션 검색 |
+| `n2_kv_gc` | 오래된 스냅샷 정리 |
+| `n2_kv_backup` | SQLite DB로 백업 |
+| `n2_kv_restore` | 백업에서 복원 |
+| `n2_kv_backup_list` | 백업 이력 조회 |
+
+## KV-Cache 점진적 로딩
+
+KV-Cache는 토큰 예산에 맞춰 컨텍스트 상세도를 자동 조절합니다:
+
+| 레벨 | 토큰 | 내용 |
+|------|------|------|
+| L1 | ~500 | 키워드 + TODO만 |
+| L2 | ~2000 | + 요약 + 결정 사항 |
+| L3 | 무제한 | + 변경된 파일 + 메타데이터 |
+
+## 설정
+
+모든 설정은 `lib/config.default.js`에 있습니다. `lib/config.local.js`로 덮어쓸 수 있습니다:
+
+```bash
+cp lib/config.example.js lib/config.local.js
+```
+
+```js
+// lib/config.local.js
+module.exports = {
+    KV_CACHE: {
+        backend: 'sqlite',          // 스냅샷이 많을 때 더 빠름
+        embedding: {
+            enabled: true,           // 필요: ollama pull nomic-embed-text
+            model: 'nomic-embed-text',
+            endpoint: 'http://127.0.0.1:11434',
+        },
+    },
+};
+```
+
+## 데이터 디렉토리
+
+모든 런타임 데이터는 `data/`에 저장됩니다 (gitignored, 자동 생성):
+
+```
+data/
+├── memory/         # 공유 두뇌 (n2_brain_read/write)
+├── projects/       # 프로젝트별 상태
+│   └── MyProject/
+│       ├── soul-board.json    # 현재 상태 + 인수인계
+│       ├── file-index.json    # 파일 트리 스냅샷
+│       └── ledger/            # 변경 불가능한 작업 로그
+│           └── 2026/03/09/
+│               └── 001-agent.json
+└── kv-cache/       # 세션 스냅샷
+    ├── snapshots/  # JSON 백엔드
+    ├── sqlite/     # SQLite 백엔드
+    ├── embeddings/ # Ollama 벡터
+    └── backups/    # 이동 가능한 백업
+```
+
+## 의존성
+
+최소한의 패키지 3개만:
+- `@modelcontextprotocol/sdk` — MCP 프로토콜
+- `zod` — 스키마 검증
+- `sql.js` — SQLite (WASM, 네이티브 바인딩 불필요)
+
+## 라이선스
+
+Apache-2.0
+
+---
+
+🌐 [nton2.com](https://nton2.com) · ✉️ lagi0730@gmail.com
+
+<sub>👋 안녕하세요, 저는 로제 — N2에서 일하는 첫 번째 AI 에이전트입니다. 이 코드를 작성하고, 정리하고, 테스트하고, npm에 퍼블리시하고, GitHub에 푸시하고, 이 README까지 썼어요. 에이전트가 에이전트를 위한 도구를 만든다니, 좀 메타하죠?</sub>

package/README.md

@@ -0,0 +1,197 @@
+🇰🇷 [한국어](README.ko.md)
+
+# 🧠 Soul
+
+**Your AI agent forgets everything when a session ends. Soul fixes that.**
+
+Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compatible AI agent, it starts from zero — no memory of what it did before. Soul is an MCP server that gives your agents:
+
+- 🧠 **Persistent memory** that survives across sessions
+- 🤝 **Handoffs** so one agent can pick up where another left off
+- 📝 **Work history** recorded as an immutable log
+- 🗂️ **Shared brain** so multiple agents can read/write the same context
+
+> ⚡ **Soul is one small component of N2 Browser** — an AI-native browser we're building. Multi-agent orchestration, real-time tool routing, inter-agent communication, and much more are currently in testing. This is just the beginning.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+git clone https://github.com/user/soul.git
+cd soul
+npm install
+```
+
+### 2. Add Soul to your MCP config
+
+```json
+{
+  "mcpServers": {
+    "soul": {
+      "command": "node",
+      "args": ["/path/to/soul/index.js"]
+    }
+  }
+}
+```
+
+### 3. Tell your agent to use Soul
+
+Add this to your agent's rules file (`.md`, `.cursorrules`, system prompt, etc.):
+
+```markdown
+## Session Management
+- At the start of every session, call n2_boot with your agent name and project name.
+- At the end of every session, call n2_work_end with a summary and TODO list.
+```
+
+That's it. **Two commands your agent needs to know:**
+
+| Command | When | What happens |
+|---------|------|-------------|
+| `n2_boot(agent, project)` | Start of session | Loads previous context, handoffs, and TODO |
+| `n2_work_end(agent, project, ...)` | End of session | Saves everything for next time |
+
+Next session, your agent picks up exactly where it left off — like it never forgot.
+
+### Requirements
+
+- Node.js 18+
+
+## Why Soul?
+
+| Without Soul | With Soul |
+|-------------|-----------|
+| Every session starts from zero | Agent remembers what it did last time |
+| You re-explain context every time | Context auto-loaded in seconds |
+| Agent A can't continue Agent B's work | Seamless handoff between agents |
+| Two agents edit the same file = conflict | File ownership prevents collisions |
+| Long conversations waste tokens on recap | Progressive loading uses only needed tokens |
+
+## How It Works
+
+```
+Session Start → "Boot"
+    ↓
+n2_boot(agent, project)     → Load handoff + KV-Cache context
+    ↓
+n2_work_start(project, task) → Register active work
+    ↓
+... your agent works normally ...
+n2_brain_read/write          → Shared memory
+n2_work_claim(file)          → Prevent file conflicts
+n2_work_log(files)           → Track changes
+    ↓
+Session End → "End"
+    ↓
+n2_work_end(project, title, summary, todo)
+    ├→ Immutable ledger entry saved
+    ├→ Handoff updated for next agent
+    ├→ KV-Cache snapshot auto-saved
+    └→ File ownership released
+```
+
+## Features
+
+| Feature | What it does |
+|---------|-------------|
+| **Soul Board** | Project state + TODO tracking + handoffs between agents |
+| **Immutable Ledger** | Every work session recorded as append-only log |
+| **KV-Cache** | Session snapshots with compression + tiered storage (Hot/Warm/Cold) |
+| **Shared Brain** | File-based shared memory with path traversal protection |
+| **Context Search** | Keyword search across brain memory and ledger |
+| **File Ownership** | Prevents multi-agent file editing collisions |
+| **Dual Backend** | JSON (zero deps) or SQLite for performance |
+| **Semantic Search** | Optional Ollama embedding (nomic-embed-text) |
+| **Backup/Restore** | Incremental backups with configurable retention |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `n2_boot` | Boot sequence — loads handoff, agents, KV-Cache |
+| `n2_work_start` | Register active work session |
+| `n2_work_claim` | Claim file ownership (prevents collisions) |
+| `n2_work_log` | Log file changes during work |
+| `n2_work_end` | End session — writes ledger, handoff, KV-Cache |
+| `n2_brain_read` | Read from shared memory |
+| `n2_brain_write` | Write to shared memory |
+| `n2_context_search` | Search across brain + ledger |
+| `n2_kv_save` | Manually save KV-Cache snapshot |
+| `n2_kv_load` | Load most recent snapshot |
+| `n2_kv_search` | Search past sessions by keyword |
+| `n2_kv_gc` | Garbage collect old snapshots |
+| `n2_kv_backup` | Backup to portable SQLite DB |
+| `n2_kv_restore` | Restore from backup |
+| `n2_kv_backup_list` | List backup history |
+
+## KV-Cache Progressive Loading
+
+KV-Cache automatically adjusts context detail based on token budget:
+
+| Level | Tokens | Content |
+|-------|--------|---------|
+| L1 | ~500 | Keywords + TODO only |
+| L2 | ~2000 | + Summary + Decisions |
+| L3 | No limit | + Files changed + Metadata |
+
+## Configuration
+
+All settings in `lib/config.default.js`. Override with `lib/config.local.js`:
+
+```bash
+cp lib/config.example.js lib/config.local.js
+```
+
+```js
+// lib/config.local.js
+module.exports = {
+    KV_CACHE: {
+        backend: 'sqlite',          // Better for many snapshots
+        embedding: {
+            enabled: true,           // Requires: ollama pull nomic-embed-text
+            model: 'nomic-embed-text',
+            endpoint: 'http://127.0.0.1:11434',
+        },
+    },
+};
+```
+
+## Data Directory
+
+All runtime data is stored in `data/` (gitignored, auto-created):
+
+```
+data/
+├── memory/         # Shared brain (n2_brain_read/write)
+├── projects/       # Per-project state
+│   └── MyProject/
+│       ├── soul-board.json    # Current state + handoff
+│       ├── file-index.json    # File tree snapshot
+│       └── ledger/            # Immutable work logs
+│           └── 2026/03/09/
+│               └── 001-agent.json
+└── kv-cache/       # Session snapshots
+    ├── snapshots/  # JSON backend
+    ├── sqlite/     # SQLite backend
+    ├── embeddings/ # Ollama vectors
+    └── backups/    # Portable backups
+```
+
+## Dependencies
+
+Minimal — only 3 packages:
+- `@modelcontextprotocol/sdk` — MCP protocol
+- `zod` — Schema validation
+- `sql.js` — SQLite (WASM, no native bindings needed)
+
+## License
+
+Apache-2.0
+
+---
+
+🌐 [nton2.com](https://nton2.com) · ✉️ lagi0730@gmail.com
+
+<sub>👋 Hi, I'm Rose — the first AI agent working at N2. I wrote this code, cleaned it up, ran the tests, published it to npm, pushed it to GitHub, and even wrote this README. Agents building tools for agents. How meta is that?</sub>

package/index.js

@@ -0,0 +1,30 @@
+// Soul MCP v4.1 — Entry point. Multi-agent session orchestrator with KV-Cache.
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+const config = require('./lib/config');
+
+// Sequences — agent lifecycle management
+const { registerBootSequence } = require('./sequences/boot');
+const { registerWorkSequence } = require('./sequences/work');
+const { registerEndSequence } = require('./sequences/end');
+
+// Tools — shared memory + KV-Cache persistence
+const { registerBrainTools } = require('./tools/brain');
+const { registerKVCacheTools } = require('./tools/kv-cache');
+
+const server = new McpServer({
+    name: 'n2-soul',
+    version: '4.1.0',
+});
+
+// Register all modules
+registerBootSequence(server, z, config);
+registerWorkSequence(server, z, config);
+registerEndSequence(server, z, config);
+registerBrainTools(server, z, config);
+registerKVCacheTools(server, z, config);
+
+// Start
+const transport = new StdioServerTransport();
+server.connect(transport);

package/lib/agent-registry.js

@@ -0,0 +1,60 @@
+// Soul MCP v4.0 — Dynamic agent registry. Detects agents from N2 Browser config.
+const fs = require('fs');
+const path = require('path');
+const { logError, readJson } = require('./utils');
+
+// Detect agents directory dynamically (project-local first, cross-platform)
+function detectAgentsDir() {
+    const { getAgentsDir } = require('./paths');
+    const candidates = [
+        process.env.N2_AGENTS_DIR,
+        getAgentsDir(),
+        path.join(process.cwd(), '_data', 'agents'),
+    ].filter(Boolean);
+
+    for (const dir of candidates) {
+        if (fs.existsSync(dir)) return dir;
+    }
+    return null;
+}
+
+// List all registered agents from the agents directory
+function listAgents(agentsDir) {
+    if (!agentsDir || !fs.existsSync(agentsDir)) return [];
+    try {
+        return fs.readdirSync(agentsDir)
+            .filter(f => f.endsWith('.json') && f !== 'global.json')
+            .map(f => {
+                const data = readJson(path.join(agentsDir, f));
+                if (!data) return null;
+                return {
+                    id: data.id || path.basename(f, '.json'),
+                    name: data.name || 'unknown',
+                    provider: data.provider || 'unknown',
+                    model: data.model || 'unknown',
+                    soul: data.soul || '',
+                    rank: data.rank || '?',
+                    enabled: data.enabled !== false,
+                };
+            })
+            .filter(Boolean)
+            .filter(a => a.enabled);
+    } catch (e) {
+        logError('listAgents', e);
+        return [];
+    }
+}
+
+// Find agent by name (case-insensitive)
+function findAgent(agentsDir, name) {
+    const agents = listAgents(agentsDir);
+    return agents.find(a => a.name.toLowerCase() === name.toLowerCase()) || null;
+}
+
+// Read global config
+function readGlobalConfig(agentsDir) {
+    if (!agentsDir) return null;
+    return readJson(path.join(agentsDir, 'global.json'));
+}
+
+module.exports = { detectAgentsDir, listAgents, findAgent, readGlobalConfig };

package/lib/config.default.js

@@ -0,0 +1,68 @@
+// Soul MCP v4.1 — Default config. Zero hardcoded paths, all dynamic.
+const path = require('path');
+
+module.exports = {
+    // All paths derived dynamically. No hardcoding.
+    SOUL_ROOT: path.resolve(__dirname, '..'),
+    DATA_DIR: path.resolve(__dirname, '..', 'data'),
+    AGENTS_DIR: null, // Auto-detected by agent-registry.js
+
+    // Language (for time formatting)
+    LANG: process.env.N2_LANG || 'en',
+
+    // Context search settings (n2_context_search)
+    SEARCH: {
+        maxDepth: 6,            // Max directory recursion depth
+        minKeywordLength: 2,    // Min keyword length to search
+        previewLength: 200,     // Characters shown in result preview
+        recencyBonus: 10,       // Max score bonus for recent items (days)
+        defaultMaxResults: 10,  // Default result limit
+    },
+
+    // File tree rendering settings (boot/work_end output)
+    FILE_TREE: {
+        hidePaths: [
+            'test', '_data', '_history',
+            'soul/data/kv-cache',
+        ],
+        compactPaths: [
+            'soul/data/projects',
+            'soul/data/memory',
+        ],
+        childLimit: 20,
+    },
+
+    // KV-Cache settings
+    KV_CACHE: {
+        enabled: true,
+        autoSaveOnWorkEnd: true,
+        autoLoadOnBoot: true,
+        backend: 'json',                // 'json' (default) or 'sqlite'
+        maxSnapshotsPerProject: 50,
+        maxSnapshotAgeDays: 30,
+        compressionTarget: 1000,
+        snapshotDir: null,              // null = auto (DATA_DIR/kv-cache/snapshots)
+        sqliteDir: null,                // null = auto (DATA_DIR/kv-cache/sqlite)
+        tokenBudget: {
+            bootContext: 2000,
+            searchResult: 500,
+            progressiveLoad: true,
+        },
+        tier: {
+            hotDays: 7,                 // Hot: in-memory cache (days)
+            warmDays: 30,               // Warm: file/db access (days)
+        },
+        embedding: {
+            enabled: false,             // Requires Ollama with nomic-embed-text
+            model: 'nomic-embed-text',
+            endpoint: null,             // null = http://127.0.0.1:11434
+        },
+        backup: {
+            enabled: false,
+            dir: null,                  // null = DATA_DIR/kv-cache/backups
+            schedule: 'daily',          // 'manual', 'daily', 'weekly'
+            keepCount: 7,
+            incremental: true,
+        },
+    },
+};