n2-soul 7.0.5 → 8.0.0

package/README.md

@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 [![npm downloads](https://img.shields.io/npm/dm/n2-soul.svg)](https://www.npmjs.com/package/n2-soul)
+[![v8.0.0](https://img.shields.io/badge/v8.0.0-Forgetting%20Curve-blueviolet.svg)](#whats-new-in-v80)
 
 **Your AI agent forgets everything when a session ends. Soul fixes that.**
 
@@ -25,6 +26,7 @@ Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compati
 
 ## Table of Contents
 
+- [What's New in v8.0](#whats-new-in-v80)
 - [Quick Start](#quick-start)
 - [Why Soul?](#why-soul)
 - [Token Efficiency](#token-efficiency)
@@ -39,6 +41,61 @@ Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compati
 - [Contributing](#contributing)
 - [Sponsors](#-sponsors)
 
+## What's New in v8.0
+
+> **Forgetting Curve — Soul now remembers what matters and forgets what doesn't.**
+
+### 🧠 Intelligent Memory (Forgetting Curve GC)
+
+Inspired by Ebbinghaus' forgetting curve, Soul v8.0 intelligently manages memory retention:
+
+```
+retention = importance × (1 + log₂(1 + accessCount)) × e^(−λ × ageDays)
+```
+
+- **Frequently accessed** sessions are kept longer
+- **Important** snapshots resist decay
+- **Stale** memory is automatically pruned via 3-tier lifecycle:
+
+| Tier | Age | Storage |
+|------|-----|--------|
+| 🔴 Hot | 0–7 days | In-memory cache + disk |
+| 🟡 Warm | 8–30 days | Disk only |
+| 🔵 Cold | 30+ days | Archived (compressed) |
+
+### ⚡ Performance Revolution — Async I/O
+
+All hot-path I/O operations are now fully asynchronous:
+
+| Operation | v7 (sync) | v8 (async) | Improvement |
+|-----------|-----------|------------|-------------|
+| KV Save | Blocks event loop | Non-blocking | ∞ (no block) |
+| KV Load | 1.2ms (blocking) | 0.7ms (async) | 42% faster |
+| KV Search | Blocks | Parallel | 3x+ throughput |
+| GC | Blocks during sweep | Background | Non-disruptive |
+
+### 🔧 SDK Native Migration
+
+- Removed legacy `registerTool` shim → direct `server.tool()` API
+- Strict schema validation: `z.any()` eliminated from all tool definitions
+- Full MCP SDK v1.6.1 compatibility
+
+### 📦 Schema v2 (Backward Compatible)
+
+Snapshots now include Forgetting Curve metadata. Existing v1 snapshots are **auto-migrated** on first load:
+
+```diff
++ accessCount: 0        // How often this snapshot was accessed
++ lastAccessed: null     // When it was last loaded
++ importance: 0.5        // 0.0–1.0 importance score
++ tier: 'warm'           // hot / warm / cold
+```
+
+> [!NOTE]
+> **Upgrading from v7.x**: Zero breaking changes. All existing data works as-is. Snapshots are transparently migrated to schema v2 on first access.
+
+---
+
 ## Quick Start
 
 ### 1. Install
@@ -224,10 +281,13 @@ n2_work_end(project, title, summary, todo, entities, insights)
 | **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) |
+| **Forgetting Curve GC** | 🆕 v8 — Ebbinghaus-based intelligent memory retention |
+| **Async I/O** | 🆕 v8 — Non-blocking I/O on all hot-path operations |
+| **Schema v2** | 🆕 v8 — Access tracking + importance scoring + auto-migration |
 | **Shared Brain** | File-based shared memory with path traversal protection |
-| **Entity Memory** | 🆕 Auto-tracks people, hardware, projects, concepts across sessions |
-| **Core Memory** | 🆕 Agent-specific always-loaded facts (identity, rules, focus) |
-| **Autonomous Extraction** | 🆕 Auto-saves entities and insights at session end |
+| **Entity Memory** | Auto-tracks people, hardware, projects, concepts across sessions |
+| **Core Memory** | Agent-specific always-loaded facts (identity, rules, focus) |
+| **Autonomous Extraction** | Auto-saves entities and insights at session end |
 | **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 |
@@ -301,9 +361,18 @@ Soul's data is **100% plain JSON files** — `soul-board.json`, ledger entries,
 
 As agents run hundreds of sessions, file count inevitably grows. Soul handles this infinite growth gracefully:
 
-### 1. KV-Cache Garbage Collection (`n2_kv_gc`)
-Soul includes a built-in `n2_kv_gc` tool that automatically cleans up old KV-Cache snapshots. 
-Set `maxAgeDays` in your config, and Soul will autonomously delete stale session data while preserving recent history.
+### 1. Forgetting Curve GC (`n2_kv_gc`) — 🆕 v8.0
+
+Soul v8.0 replaces simple age-based deletion with **Ebbinghaus Forgetting Curve** scoring:
+
+```
+retention = importance × (1 + log₂(1 + accessCount)) × e^(−0.05 × ageDays)
+```
+
+- Snapshots with high `importance` or frequent `accessCount` survive longer
+- Snapshots decay naturally over time (λ = 0.05)
+- Retention threshold: 0.1 (below this → eligible for deletion)
+- `n2_kv_gc` reports retention scores so you can monitor memory health
 
 ### 2. Time-Partitioned Ledger
 The immutable work ledger isn't a single massive database file. It's partitioned by date (`ledger/YYYY/MM/DD/`). 
@@ -547,7 +616,7 @@ Soul is free and open-source. These amazing people help keep it alive:
 
 ## Star History
 
-If you find Soul helpful, please consider giving us a star! ⭐
+No coffee? A star is fine too ☕→⭐
 
 ---
 

package/docs/soul-notebooklm-source.md

@@ -0,0 +1,127 @@
+# Soul — The Memory System That Makes AI Agents Actually Useful
+
+## The Problem Nobody Talks About
+
+Every time you open a new chat with Cursor, VS Code Copilot, Claude, or any AI coding assistant, your agent starts from absolute zero. It doesn't know what you worked on yesterday. It doesn't know what files it changed. It doesn't remember the bug it found 3 hours ago. It's like having a brilliant developer with permanent amnesia.
+
+You end up spending the first 5-10 minutes of every session re-explaining context. "Remember the auth module? The one with JWT? We added rate limiting yesterday..." — and the agent has no idea.
+
+**This is the single biggest productivity killer in AI-assisted development today.** Not model intelligence. Not context window size. Memory loss.
+
+## What Soul Does
+
+Soul is an open-source MCP (Model Context Protocol) server that gives AI agents persistent memory. Install it once, and your agents remember everything — across sessions, across agents, across days.
+
+### The Magic: Two Commands
+
+```
+Session start: n2_boot("rose", "my-project")  → Agent loads all previous context
+Session end:   n2_work_end(...)                → Agent saves everything for next time
+```
+
+That's it. Next session, your agent picks up exactly where it left off.
+
+## Key Features That Make Soul Special
+
+### 1. Persistent Memory (KV-Cache)
+Every session is automatically saved as a snapshot. When you start a new session, Soul loads the previous context using progressive levels:
+- **L1 (~500 tokens)**: Just keywords and TODO — ultra-fast startup
+- **L2 (~2,000 tokens)**: Summary + decisions + context
+- **L3 (full)**: Complete session restore
+
+This means over 10 sessions, you save 30,000+ tokens on context alone.
+
+### 2. Multi-Agent Handoffs
+Agent Rose works on the auth module at 2pm. Agent Jenny picks up at 5pm. With Soul, Jenny knows exactly what Rose did, what's left to do, and what files were changed. No re-explanation needed.
+
+### 3. Entity Memory (v5.0)
+Soul automatically tracks people, hardware, projects, and concepts across sessions. Every entity is stored with attributes and auto-merged when updated.
+
+### 4. Core Memory (v5.0)
+Agent-specific facts that are always loaded at boot. An agent's identity, working rules, current focus — always available, never forgotten.
+
+### 5. Shared Brain
+Multiple agents can read and write to the same shared memory space. File-based, simple, with path traversal protection built in.
+
+### 6. Immutable Ledger
+Every work session is recorded as an append-only log. You can trace exactly what happened, when, and by whom.
+
+### 7. File Ownership
+Prevents two agents from editing the same file simultaneously. Simple, effective collision prevention.
+
+## Ark — Built-in AI Safety (v6.0)
+
+This is the feature that got people really excited on Reddit.
+
+### The Problem
+AI agents with tool access can execute dangerous commands. `rm -rf /` to delete everything. `DROP DATABASE` to destroy data. `git push --force` to rewrite history. These aren't hypothetical — autonomous agents have already done these things.
+
+### Ark's Solution: Zero-Token Safety
+
+Most AI safety solutions use another LLM to check if an action is safe. That costs 500-2,000 tokens per check and takes 1-5 seconds.
+
+**Ark uses pure regex pattern matching inside the MCP server.** Zero tokens. Less than 1 millisecond. Always on — there's no toggle to disable it. It's like a firewall for your AI.
+
+Key properties:
+- **Zero token cost** — runs in Node.js, not in the LLM
+- **Zero latency** — microsecond execution
+- **Always on** — no `enabled: false` option (by design)
+- **Self-protecting** — 4 layers prevent a rogue AI from disabling Ark itself
+- **Human-readable rules** — `.n2` files anyone can read and customize
+- **7 industry templates** — Medical (HIPAA), Military, Finance, Legal, Privacy (GDPR), Autonomous, DevOps
+
+### .n2 Rule Files
+
+Safety rules are written in a human-readable format:
+
+```
+@rule catastrophic_destruction {
+    scope: all
+    blacklist: [/rm\s+-rf/, /DROP\s+DATABASE/i, /git\s+push\s+--force/i]
+    requires: human_approval
+}
+```
+
+Transparent, auditable, customizable. No black boxes.
+
+## Cloud Storage (v6.1) — Zero-Cost Cloud in One Line
+
+Soul takes a radically different approach to cloud storage:
+
+```js
+DATA_DIR: 'G:/My Drive/n2-soul'  // That's it. Your AI memory is now in Google Drive.
+```
+
+Because Soul stores everything as plain JSON files, any folder sync service works as cloud storage. Google Drive (free 15GB), OneDrive, Dropbox, NAS, USB drive — all supported. Zero API keys. Zero monthly fees. Zero vendor lock-in.
+
+For teams, point multiple agents to the same network path = instant shared memory with zero setup.
+
+## The Numbers
+
+- **41 GitHub stars in 2 days** (after Reddit launch)
+- **7 forks** — people are actively building on it
+- **v6.1.4** — actively maintained, shipping weekly
+- **Only 3 dependencies** — minimal, lightweight, reliable
+- **Node.js 18+** — runs anywhere
+- **Apache-2.0 license** — fully open source
+
+## The Story Behind Soul
+
+Soul was created by a developer who came back to coding after 30 years. The frustration of watching AI agents forget everything between sessions was the catalyst. "I built Soul because it broke my heart watching my agents lose their memory every session."
+
+What started as a personal tool grew into something the community actually wanted. The project went from zero to 41 stars in just two days after being posted on Reddit, with engaged discussions about enterprise use cases like Vault mode for secret management.
+
+## Why Soul Matters
+
+In the AI agent ecosystem, there are tools for making agents smarter (better models), tools for giving agents abilities (MCP servers), but almost nothing for giving agents **memory**. Soul fills that gap.
+
+The vision: AI agents that truly know you, your codebase, your preferences. Agents that can hand off work to each other seamlessly. Agents that are safe by default, not by hope.
+
+**Soul is the memory layer the AI ecosystem has been missing.**
+
+---
+
+🔗 GitHub: github.com/choihyunsus/soul
+📦 npm: n2-soul
+🌐 Website: nton2.com
+💖 Sponsor: github.com/sponsors/choihyunsus

package/docs/soul-v8-roadmap.md

@@ -0,0 +1,152 @@
+# 🧠 Soul v8.0 Roadmap — The Heart Upgrade
+
+> 기획일: 2026-03-26 | 상태: Planning
+
+## 배경
+
+Soul은 N2 생태계의 **심장**이다. 다른 패키지(Clotho, Ark, Arachne, QLN, Mimir)는 옵션이지만 Soul 없이는 아무것도 돌아가지 않는다.
+
+현재 Soul v7.0.6은 초창기 CJS로 작성되었고, 아키텍처는 탄탄하지만 품질 인프라(타입, 테스트, 로깅)와 성능 최적화(동기I/O, O(n) 검색)에 약점이 있다.
+
+**목표**: 구조를 망가뜨리지 않으면서 2중 3중으로 안전하고 빠르게 업그레이드한다. 메모리 관련이므로 무겁지 않게.
+
+---
+
+## Phase 1: 기반 다지기 ✅ 완료 (v7.1)
+
+| 항목 | 상태 | 설명 |
+|------|:----:|------|
+| description 업데이트 | ✅ | Ark/Arachne 구식 참조 제거 |
+| 4레벨 로그 시스템 | ✅ | debug/info/warn/error + `N2_LOG_LEVEL` 환경변수 제어 |
+| info 레벨 로그 정확화 | ✅ | logError 남용 → logInfo 수정 (3곳) |
+| Board 인메모리 캐시 | ✅ | mtime 기반 무효화로 멀티에이전트 안전성 유지 |
+
+---
+
+## Phase 2: 성능 혁신
+
+| 항목 | 난이도 | 설명 |
+|------|:------:|------|
+| sqlite-vec 벡터 인덱스 | 🟡 | 시맨틱 검색 O(n) → O(1). sqlite-vec 이미 의존성에 있음 |
+| 핫 패스 async I/O | 🟠 | save/load/search의 동기 I/O → 비동기 전환 |
+| registerTool shim 제거 | 🟡 | MCP SDK 네이티브 사용으로 기술부채 해소 |
+
+---
+
+## Phase 3: Forgetting Curve — 인간형 기억 시스템
+
+> Soul 단독으로 구현 가능. 가장 즉각적인 효과.
+
+현재: 스냅샷 50개 제한, 30일 만료 → 기계적 삭제
+
+### 3단계 기억 계층
+
+```
+┌──────────────────────────────────────────────┐
+│  🔴 Hot Memory (최근 7일 + 자주 접근)         │
+│  → 전체 스냅샷 보관                           │
+│  → 즉시 로드 가능                             │
+├──────────────────────────────────────────────┤
+│  🟡 Warm Memory (7~30일)                     │
+│  → 요약 + 핵심 결정사항만 보관                 │
+│  → 토큰 절약 80%+                            │
+├──────────────────────────────────────────────┤
+│  🔵 Cold Memory (30일+)                      │
+│  → 키워드 + 메타데이터만 보관                  │
+│  → 필요 시 백업에서 전체 복원                  │
+│  → 메모리 사용량 95% 감소                     │
+└──────────────────────────────────────────────┘
+```
+
+### 접근 빈도 기반 승격/강등
+
+```
+기억 A: 매일 검색됨         → Hot 유지
+기억 B: 2주 전 마지막 접근   → Warm으로 강등
+기억 C: 2달 전, 한 번도 검색 안 됨 → Cold로 강등
+기억 D: Cold인데 갑자기 검색됨 → Warm으로 승격
+```
+
+---
+
+## Phase 4: Soul × Arachne 연동
+
+> Arachne의 코드 이해 능력을 Soul의 기억에 결합
+
+### Smart Memory Compression
+- 현재: 텍스트 길이 기반 단순 압축
+- 연동 후: Arachne의 BM25로 현재 프로젝트와 관련 있는 기억은 유지, 무관한 건 축소
+- 같은 토큰 예산으로 **2-3배 더 정확한 컨텍스트**
+
+### Memory-Aware Code Search
+- Soul이 "이 에이전트가 지난 세션에 수정한 파일" 정보를 Arachne에 전달
+- Arachne가 검색 우선순위를 자동 조정
+- 에이전트가 최근 작업한 파일이 검색 상위에 노출
+
+### Cross-Session Impact Analysis
+- Soul: "지난 세션에 auth.ts를 수정했다"
+- Arachne: "auth.ts를 import하는 파일 15개가 영향받을 수 있다"
+- 부팅 시 자동으로 영향 범위 알림
+
+---
+
+## Phase 5: Soul × Mimir 연동
+
+> Mimir의 경험 학습을 Soul의 세션 데이터에 적용
+
+### Auto-Learning Ledger
+```
+작업 끝 → Ledger에 기록 → Mimir가 자동 분석
+→ "TypeScript strict 프로젝트에서 interface 대신 type 썼을 때 3번 수정함"
+→ 다음에 같은 상황이면 자동으로 interface 추천
+```
+- 모든 작업 세션이 자동으로 학습 데이터가 된다
+- 명시적 `study_start/add/end` 없이도 학습
+
+### Experience-Guided Decisions
+- 비슷한 상황에서 과거 어떤 결정을 했는지 자동 서제스트
+- Ledger의 `decisions` 필드를 Mimir가 분석
+- "이전에 비슷한 리팩토링에서 X 접근법을 선택했고 성공했다"
+
+---
+
+## Phase 6: 3자 연동 — Predictive Context Loading
+
+> 가장 복잡하지만 가장 강력한 기능
+
+```
+부팅:
+  1. Soul   → 이전 세션 KV-Cache 로드
+  2. Mimir  → 패턴 분석: "이 에이전트는 보통 이 시간에 이 프로젝트의 이런 작업을 한다"
+  3. Arachne → 예측된 작업에 필요한 코드 컨텍스트를 미리 로드
+
+결과: 에이전트가 질문하기도 전에 필요한 정보가 준비되어 있다
+```
+
+---
+
+## Phase 7: 품질 보증
+
+| 항목 | 설명 |
+|------|------|
+| 유닛 테스트 20개+ | SoulEngine, KV-Cache save/load/search, Board 캐시 |
+| 통합 테스트 | 부팅 → 작업 → 종료 전체 시퀀스 |
+| CI/CD | GitHub Actions 자동 테스트 |
+| TypeScript 검토 | JSDoc `@ts-check` 또는 전면 마이그레이션 결정 |
+
+---
+
+## 우선순위 요약
+
+```
+즉시    Phase 1 ✅ → 로그, 캐시, description
+단기    Phase 2    → sqlite-vec, async I/O
+중기    Phase 3    → Forgetting Curve (Soul 단독)
+중장기  Phase 4-5  → Arachne/Mimir 연동
+장기    Phase 6    → 3자 연동 (Predictive Loading)
+지속    Phase 7    → 테스트, 타입
+```
+
+---
+
+> *"Soul은 기억이다. 기억이 효율적이면 AI는 더 빠르고, 더 정확하고, 더 성장한다."*

package/index.js

@@ -1,21 +1,17 @@
-// Soul MCP v7.0 — Entry point. Multi-agent session orchestrator with KV-Cache + Ark + Arachne.
-const path = require('path');
+// Soul MCP v8.0 — 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');
-const { createArk } = require('./lib/ark');
-const { createArachne } = require('./lib/arachne');
 
 // 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 + code context
+// Tools — shared memory + KV-Cache persistence
 const { registerBrainTools } = require('./tools/brain');
 const { registerKVCacheTools } = require('./tools/kv-cache');
-const { registerArachneTools } = require('./tools/arachne');
 
 const pkg = require('./package.json');
 const server = new McpServer({
@@ -23,80 +19,15 @@ const server = new McpServer({
     version: pkg.version,
 });
 
-// ═══════════════════════════════════════════════════════
-// Ark — THE LAST SHIELD
-// "You shall not pass."
-//
-// Pure & simple: every tool call → check against rules.
-// No tool classification. No special cases.
-// 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,
-    auditMaxAgeDays: config.ARK?.auditMaxAgeDays ?? 7,
-    auditEnabled: true,
-});
-
-// Ark-wrapped registerTool shim — bridges legacy registerTool() to SDK v1.6.1 server.tool()
-const _origTool = server.tool.bind(server);
-const _arkWrap = (name, handler) => async (args) => {
-    const content = JSON.stringify(args);
-    const result = ark.check(name, content, 'tool_call');
-    if (!result.allowed) {
-        return {
-            content: [{
-                type: 'text',
-                text: `[n2-ark] BLOCKED: ${result.reason}\n` +
-                      `Rule: ${result.rule} | Action: ${result.action}\n` +
-                      `This action requires human approval.`,
-            }],
-        };
-    }
-    return handler(args);
-};
-// Shim: server.registerTool(name, {title, description, inputSchema}, handler) → server.tool()
-server.registerTool = (name, schema, handler) => {
-    const desc = schema.description || schema.title || name;
-    _origTool(name, desc, schema.inputSchema || {}, _arkWrap(name, handler));
-};
-// Override: server.tool() with Ark check (for files using new API directly, e.g. arachne.js)
-server.tool = (name, ...rest) => {
-    const handler = rest.pop();
-    _origTool(name, ...rest, _arkWrap(name, handler));
-};
-// ═══ End Ark ═══
-
-// Register core modules (all tools pass through Ark)
-registerBootSequence(server, z, config, ark.workflows);
+// Register core modules — all tools use SDK-native server.tool() directly
+registerBootSequence(server, z, config);
 registerWorkSequence(server, z, config);
 registerEndSequence(server, z, config);
 registerBrainTools(server, z, config);
 registerKVCacheTools(server, z, config);
 
-// ═══════════════════════════════════════════════════════
-// Arachne — THE GREATEST WEAVER
-// Code context assembly engine — indexes codebase,
-// picks exactly what AI needs.
-// Only activates when ARACHNE config is present.
-// ═══════════════════════════════════════════════════════
+// Start MCP transport
 async function boot() {
-    // Initialize Arachne (if configured)
-    if (config.ARACHNE?.projectDir) {
-        try {
-            const arachne = await createArachne({
-                ...config.ARACHNE,
-                dataDir: config.ARACHNE.dataDir ?? path.join(config.DATA_DIR, 'arachne'),
-            });
-            registerArachneTools(server, z, arachne, config);
-            console.error(`[n2-soul] Arachne enabled: ${config.ARACHNE.projectDir}`);
-        } catch (err) {
-            console.error(`[n2-soul] Arachne init failed: ${err.message}`);
-        }
-    }
-
-    // Start MCP transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }