n2-soul 8.0.0 β†’ 9.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.ko.md +30 -17
  3. package/README.md +20 -52
  4. package/dist/index.d.ts +1 -0
  5. package/dist/index.js +33 -0
  6. package/dist/index.js.map +1 -0
  7. package/dist/types.d.ts +186 -0
  8. package/dist/types.js +4 -0
  9. package/dist/types.js.map +1 -0
  10. package/package.json +21 -4
  11. package/.github/FUNDING.yml +0 -3
  12. package/CONTRIBUTING.md +0 -142
  13. package/docs/soul-notebooklm-source.md +0 -127
  14. package/docs/soul-v8-roadmap.md +0 -152
  15. package/index.js +0 -38
  16. package/lib/agent-registry.js +0 -60
  17. package/lib/config.default.js +0 -84
  18. package/lib/config.example.js +0 -28
  19. package/lib/config.js +0 -28
  20. package/lib/context.js +0 -34
  21. package/lib/core-memory.js +0 -137
  22. package/lib/entity-memory.js +0 -219
  23. package/lib/intercom-log.js +0 -187
  24. package/lib/kv-cache/agent-adapter.js +0 -192
  25. package/lib/kv-cache/backup.js +0 -357
  26. package/lib/kv-cache/compressor.js +0 -130
  27. package/lib/kv-cache/embedding.js +0 -205
  28. package/lib/kv-cache/index.js +0 -400
  29. package/lib/kv-cache/schema.js +0 -124
  30. package/lib/kv-cache/snapshot.js +0 -320
  31. package/lib/kv-cache/sqlite-store.js +0 -402
  32. package/lib/kv-cache/tier-manager.js +0 -248
  33. package/lib/kv-cache/token-saver.js +0 -153
  34. package/lib/paths.js +0 -29
  35. package/lib/soul-engine.js +0 -234
  36. package/lib/utils.js +0 -167
  37. package/sequences/boot.js +0 -127
  38. package/sequences/end.js +0 -157
  39. package/sequences/work.js +0 -260
  40. package/tests/README.md +0 -5
  41. package/tests/test-simulation.js +0 -153
  42. package/tools/brain.js +0 -122
  43. package/tools/kv-cache.js +0 -225
package/CHANGELOG.md ADDED
@@ -0,0 +1,103 @@
1
+ # Changelog
2
+
3
+ All notable changes to Soul are documented here.
4
+
5
+ ## [9.0.0] β€” 2026-03-26
6
+
7
+ ### πŸ”’ Strict TypeScript Migration
8
+
9
+ Soul is now fully written in **TypeScript strict mode** with zero `any` usage.
10
+
11
+ #### Added
12
+ - **ESLint strict rules** β€” automated detection of floating promises, unused vars, type safety violations
13
+ - **30 unit tests** β€” utils, soul-engine, kv-cache, and dispose pattern verification
14
+ - **`npm run verify`** β€” one-command pipeline: typecheck + lint + build + test
15
+ - **`SoulKVCache.dispose()`** β€” proper timer cleanup for backup scheduler
16
+ - **`disposeWorkSequence()`** β€” GC timer cleanup for test environments
17
+ - **HTTP response size limit** (10MB) for Ollama embedding requests
18
+ - **`sql-js.d.ts`** β€” custom type declarations for sql.js WASM module
19
+
20
+ #### Fixed
21
+ - **CRITICAL**: `stmt.free()` / `embStmt.free()` now wrapped in `try/finally` blocks (WASM memory leak prevention)
22
+ - **CRITICAL**: `.catch(() => {})` silent error swallowing replaced with `logError()`
23
+ - **HIGH**: Floating promise in auto-backup timer β€” added `void` + `.catch()` error handling
24
+ - **HIGH**: `Buffer` + `string` concatenation β€” explicit `.toString()` conversion
25
+
26
+ #### Changed
27
+ - Source code migrated from CommonJS to `import/export` (ESM-style), compiled output remains CJS for compatibility
28
+ - 13 `require()` calls β†’ 9 static `import` + 4 documented lazy `require()` (circular deps, runtime optional)
29
+ - `export =` β†’ `export default` for ESM/CJS interop
30
+ - `tsconfig.json` β€” `strict: true`, `noUncheckedIndexedAccess`, `noUnusedLocals`, `noUnusedParameters`
31
+
32
+ #### Dependencies Added (devDependencies)
33
+ - `eslint` ^9.x
34
+ - `@eslint/js` ^9.x
35
+ - `typescript-eslint` ^8.x
36
+
37
+ ---
38
+
39
+ ## [8.0.0] β€” 2026-03-26
40
+
41
+ ### 🧠 Forgetting Curve β€” Intelligent Memory
42
+
43
+ Soul now remembers what matters and forgets what doesn't, inspired by Ebbinghaus' forgetting curve.
44
+
45
+ #### Added
46
+ - **Forgetting Curve GC** β€” retention formula: `importance Γ— (1 + logβ‚‚(1 + accessCount)) Γ— e^(βˆ’Ξ» Γ— ageDays)`
47
+ - **3-tier memory lifecycle** β€” Hot (0–7d, in-memory + disk) β†’ Warm (8–30d, disk) β†’ Cold (30d+, archived)
48
+ - **Async I/O** β€” all hot-path operations non-blocking (42% faster KV load, 3x+ search throughput)
49
+ - **Schema v2** β€” `accessCount`, `lastAccessed`, `importance`, `tier` fields (auto-migrated from v1)
50
+ - **SQLite backend** β€” `sql.js` WASM-based, no native bindings needed
51
+ - **Incremental backups** β€” portable SQLite backup/restore with configurable retention
52
+ - **Semantic search** β€” Ollama `nomic-embed-text` embedding integration
53
+
54
+ #### Changed
55
+ - SDK Native Migration β€” removed legacy `registerTool` shim, direct `server.tool()` API
56
+ - `z.any()` eliminated from all tool schema definitions
57
+
58
+ ---
59
+
60
+ ## [7.0.0] β€” 2026-03
61
+
62
+ ### πŸ•ΈοΈ Arachne β€” Code Context Assembly
63
+
64
+ > **Note**: Arachne has been separated into its own package [`n2-arachne`](https://github.com/choihyunsus/n2-arachne) as of v8.0.
65
+
66
+ - BM25 search + dependency tracking + smart assembly
67
+ - 50,000 file project β†’ 30 most relevant chunks β†’ 30K tokens (instead of 500K+)
68
+ - Ollama semantic search support
69
+
70
+ ---
71
+
72
+ ## [6.0.0] β€” 2026-03
73
+
74
+ ### πŸ›‘οΈ Ark β€” AI Safety System
75
+
76
+ > **Note**: Ark has been separated into its own package [`n2-ark`](https://github.com/choihyunsus/n2-ark) as of v8.0.
77
+
78
+ - Zero-token-cost safety enforcement via regex pattern matching
79
+ - Multi-layer response system (WARN β†’ MODIFY β†’ BLOCK β†’ LOCKDOWN)
80
+ - `.n2` rule file format with 7 domain templates
81
+ - Full MCP compatibility
82
+
83
+ ---
84
+
85
+ ## [5.0.0] β€” 2026-02
86
+
87
+ ### 🏷️ Entity & Core Memory
88
+
89
+ - **Entity Memory** β€” auto-track people, hardware, projects, concepts
90
+ - **Core Memory** β€” per-agent always-loaded facts
91
+ - **Auto-extraction** β€” entities and insights saved automatically at `n2_work_end`
92
+ - **Context Search** β€” keyword search across Brain + Ledger
93
+
94
+ ---
95
+
96
+ ## [4.0.0] β€” 2026-01
97
+
98
+ ### πŸ“‹ Soul Board & Ledger
99
+
100
+ - **Soul Board** β€” project state + TODO tracking + cross-agent handoff
101
+ - **Immutable Ledger** β€” append-only work logs with date-based partitioning
102
+ - **File Ownership** β€” collision prevention for multi-agent environments
103
+ - **Shared Brain** β€” file-based shared memory with path traversal protection
package/README.ko.md CHANGED
@@ -3,18 +3,6 @@
3
3
  # 🧠 Soul
4
4
 
5
5
  **AI μ—μ΄μ „νŠΈλŠ” μ„Έμ…˜μ΄ λλ‚˜λ©΄ λͺ¨λ“  κ±Έ μžŠμ–΄λ²„λ¦½λ‹ˆλ‹€. Soul이 κ·Έκ±Έ ν•΄κ²°ν•©λ‹ˆλ‹€.**
6
- **AI μ—μ΄μ „νŠΈκ°€ μœ„ν—˜ν•œ 행동을 ν•  μˆ˜λ„ μžˆμŠ΅λ‹ˆλ‹€. Arkκ°€ κ·Έκ±Έ λ§‰μŠ΅λ‹ˆλ‹€.**
7
- **AI μ—μ΄μ „νŠΈκ°€ κ΄€λ ¨ μ—†λŠ” μ½”λ“œλ₯Ό 읽느라 토큰을 λ‚­λΉ„ν•©λ‹ˆλ‹€. Arachneκ°€ κ·Έκ±Έ ν•΄κ²°ν•©λ‹ˆλ‹€.**
8
-
9
- > ### πŸš€ v7.0 μ—…λ°μ΄νŠΈ β€” Arachne
10
- >
11
- > **Arachne** β€” μ½”λ“œ μ»¨ν…μŠ€νŠΈ μ–΄μ…ˆλΈ”λ¦¬ μ—”μ§„. μ½”λ“œλ² μ΄μŠ€ 전체λ₯Ό μΈλ±μ‹±ν•˜κ³  AIμ—κ²Œ **μ •ν™•νžˆ** ν•„μš”ν•œ κ²ƒλ§Œ μ „λ‹¬ν•©λ‹ˆλ‹€.
12
- > ```
13
- > 50,000 파일 ν”„λ‘œμ νŠΈ β†’ κ°€μž₯ κ΄€λ ¨ μžˆλŠ” 30개 청크 β†’ 30K 토큰 (500K+ λŒ€μ‹ )
14
- > ```
15
- > BM25 검색 + μ˜μ‘΄μ„± 좔적 + 슀마트 μ–΄μ…ˆλΈ”λ¦¬. Ollamaλ₯Ό ν†΅ν•œ μ‹œλ§¨ν‹± 검색도 지원. [μžμ„Ένžˆ β†’](#arachne--졜고의-직쑰사)
16
- >
17
- > **Ark** (v6.0) 포함 β€” 토큰 λΉ„μš© 0으둜 μœ„ν—˜ν•œ 행동을 μ°¨λ‹¨ν•˜λŠ” AI μ•ˆμ „ μ‹œμŠ€ν…œ. [μžμ„Ένžˆ β†’](#ark--μ΅œν›„μ˜-방패)
18
6
 
19
7
  Cursor, VS Code Copilot λ“± MCP ν˜Έν™˜ AI μ—μ΄μ „νŠΈμ™€ μƒˆ μ±„νŒ…μ„ μ‹œμž‘ν•  λ•Œλ§ˆλ‹€, μ—μ΄μ „νŠΈλŠ” 이전에 뭘 ν–ˆλŠ”μ§€ μ „ν˜€ λͺ¨λ₯Έ 채 μ²˜μŒλΆ€ν„° μ‹œμž‘ν•©λ‹ˆλ‹€. Soul은 μ—μ΄μ „νŠΈμ—κ²Œ 이런 λŠ₯λ ₯을 λΆ€μ—¬ν•˜λŠ” MCP μ„œλ²„μž…λ‹ˆλ‹€:
20
8
 
@@ -22,12 +10,37 @@ Cursor, VS Code Copilot λ“± MCP ν˜Έν™˜ AI μ—μ΄μ „νŠΈμ™€ μƒˆ μ±„νŒ…μ„ μ‹œμž‘
22
10
  - 🀝 **μΈμˆ˜μΈκ³„** β€” ν•œ μ—μ΄μ „νŠΈκ°€ λ‹€λ₯Έ μ—μ΄μ „νŠΈμ˜ μž‘μ—…μ„ 이어받을 수 μžˆμŠ΅λ‹ˆλ‹€
23
11
  - πŸ“ **μž‘μ—… 이λ ₯** β€” λͺ¨λ“  μž‘μ—…μ΄ λ³€κ²½ λΆˆκ°€λŠ₯ν•œ 둜그둜 κΈ°λ‘λ©λ‹ˆλ‹€
24
12
  - πŸ—‚οΈ **곡유 λ‘λ‡Œ** β€” μ—¬λŸ¬ μ—μ΄μ „νŠΈκ°€ 같은 μ»¨ν…μŠ€νŠΈλ₯Ό 읽고 μ“Έ 수 μžˆμŠ΅λ‹ˆλ‹€
25
- - 🏷️ **μ—”ν‹°ν‹° λ©”λͺ¨λ¦¬** β€” 인물, ν•˜λ“œμ›¨μ–΄, ν”„λ‘œμ νŠΈλ₯Ό μžλ™ μΆ”μ ν•©λ‹ˆλ‹€ (v5.0)
26
- - πŸ’‘ **μ½”μ–΄ λ©”λͺ¨λ¦¬** β€” μ—μ΄μ „νŠΈλ³„ 핡심 사싀이 항상 λ‘œλ“œλ©λ‹ˆλ‹€ (v5.0)
27
- - πŸ›‘οΈ **Ark** β€” 토큰 λΉ„μš© 0으둜 μœ„ν—˜ν•œ 행동을 μ°¨λ‹¨ν•˜λŠ” AI μ•ˆμ „ μ‹œμŠ€ν…œ (v6.0)
28
- - πŸ•ΈοΈ **Arachne** β€” AIμ—κ²Œ μ •ν™•νžˆ ν•„μš”ν•œ μ½”λ“œλ§Œ μ „λ‹¬ν•˜λŠ” μ½”λ“œ μ»¨ν…μŠ€νŠΈ μ—”μ§„ (v7.0)
13
+ - 🏷️ **μ—”ν‹°ν‹° λ©”λͺ¨λ¦¬** β€” 인물, ν•˜λ“œμ›¨μ–΄, ν”„λ‘œμ νŠΈλ₯Ό μžλ™ μΆ”μ ν•©λ‹ˆλ‹€
14
+ - πŸ’‘ **μ½”μ–΄ λ©”λͺ¨λ¦¬** β€” μ—μ΄μ „νŠΈλ³„ 핡심 사싀이 항상 λ‘œλ“œλ©λ‹ˆλ‹€
29
15
 
30
- > ⚑ **Soul은 N2 Browser의 μž‘μ€ λΆ€μ†ν’ˆ ν•˜λ‚˜μž…λ‹ˆλ‹€** β€” μš°λ¦¬κ°€ λ§Œλ“€κ³  μžˆλŠ” AI λ„€μ΄ν‹°λΈŒ λΈŒλΌμš°μ €μ˜ μΌλΆ€μ˜ˆμš”. λ©€ν‹° μ—μ΄μ „νŠΈ μ˜€μΌ€μŠ€νŠΈλ ˆμ΄μ…˜, μ‹€μ‹œκ°„ 도ꡬ λΌμš°νŒ…, μ—μ΄μ „νŠΈ κ°„ 톡신 λ“± 훨씬 더 λ§Žμ€ κΈ°λŠ₯듀이 ν˜„μž¬ ν…ŒμŠ€νŠΈ μ€‘μž…λ‹ˆλ‹€. 이건 μ‹œμž‘μ— λΆˆκ³Όν•©λ‹ˆλ‹€.
16
+ > πŸ”Œ **N2 μ—μ½”μ‹œμŠ€ν…œκ³Ό 연동:**
17
+ > [**Ark**](https://github.com/choihyunsus/n2-ark) (AI μ•ˆμ „) Β· [**Arachne**](https://github.com/choihyunsus/n2-arachne) (μ½”λ“œ μ»¨ν…μŠ€νŠΈ) Β· [**QLN**](https://github.com/choihyunsus/n2-QLN) (도ꡬ λΌμš°νŒ…)
18
+
19
+ ## v9.0의 μƒˆλ‘œμš΄ κΈ°λŠ₯
20
+
21
+ > **Strict TypeScript β€” `any` 제둜, λ©”λͺ¨λ¦¬ λˆ„μˆ˜ 제둜, μžλ™ν™”λœ ν’ˆμ§ˆ 검증.**
22
+
23
+ ### πŸ”’ TypeScript Strict λͺ¨λ“œ μ „ν™˜
24
+
25
+ - μ†ŒμŠ€ μ½”λ“œ 전체λ₯Ό TypeScript `strict: true`둜 λ§ˆμ΄κ·Έλ ˆμ΄μ…˜
26
+ - **`any` μ‚¬μš© 제둜** β€” λͺ¨λ“  νƒ€μž…μ΄ λͺ…μ‹œμ μ΄κ³  검증 κ°€λŠ₯
27
+ - ESLint `strictTypeChecked` κ·œμΉ™μœΌλ‘œ floating promise, νƒ€μž… μ•ˆμ „ μœ„λ°˜ μžλ™ 탐지
28
+ - 30개 λ‹¨μœ„ ν…ŒμŠ€νŠΈ + `npm run verify` μ›μ»€λ§¨λ“œ 검증 νŒŒμ΄ν”„λΌμΈ
29
+
30
+ ### πŸ›‘οΈ λ³΄μ•ˆ & λ©”λͺ¨λ¦¬ 감사
31
+
32
+ - WASM λ©”λͺ¨λ¦¬ λˆ„μˆ˜ μˆ˜μ • β€” `stmt.free()` β†’ `try/finally` 블둝
33
+ - 무음 μ—λŸ¬ μ‚Όν‚΄ 제거 β€” λͺ¨λ“  `.catch()` ν•Έλ“€λŸ¬κ°€ μ—λŸ¬ λ‘œκΉ…
34
+ - μž„λ² λ”© μš”μ²­ HTTP 응닡 크기 μ œν•œ (10MB)
35
+ - `dispose()` λ©”μ„œλ“œλ‘œ 타이머 λˆ„μˆ˜ λ°©μ§€
36
+
37
+ ### 🧠 v8.0 κΈ°λŠ₯ (포함)
38
+
39
+ - **망각 곑선 GC** β€” μ ‘κ·Ό νŒ¨ν„΄ 기반 μ§€λŠ₯ν˜• κΈ°μ–΅ 보쑴
40
+ - **비동기 I/O** β€” λ…ΌλΈ”λ‘œν‚Ή μ—°μ‚°, KV λ‘œλ“œ 42% 빨라짐
41
+ - **3단계 λ©”λͺ¨λ¦¬** β€” Hot β†’ Warm β†’ Cold 수λͺ… μ£ΌκΈ°
42
+
43
+ > 전체 버전 νžˆμŠ€ν† λ¦¬λŠ” [CHANGELOG.md](CHANGELOG.md)λ₯Ό μ°Έκ³ ν•˜μ„Έμš”.
31
44
 
32
45
  ## λΉ λ₯Έ μ‹œμž‘
33
46
 
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
7
7
  [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
8
8
  [![npm downloads](https://img.shields.io/npm/dm/n2-soul.svg)](https://www.npmjs.com/package/n2-soul)
9
- [![v8.0.0](https://img.shields.io/badge/v8.0.0-Forgetting%20Curve-blueviolet.svg)](#whats-new-in-v80)
9
+ [![v9.0.0](https://img.shields.io/badge/v9.0.0-Strict%20TypeScript-blueviolet.svg)](#whats-new-in-v90)
10
10
 
11
11
  **Your AI agent forgets everything when a session ends. Soul fixes that.**
12
12
 
@@ -26,73 +26,41 @@ Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compati
26
26
 
27
27
  ## Table of Contents
28
28
 
29
- - [What's New in v8.0](#whats-new-in-v80)
29
+ - [What's New in v9.0](#whats-new-in-v90)
30
30
  - [Quick Start](#quick-start)
31
31
  - [Why Soul?](#why-soul)
32
- - [Token Efficiency](#token-efficiency)
33
- - [How It Works](#how-it-works)
34
32
  - [Features](#features)
35
33
  - [Cloud Storage](#️-cloud-storage--store-your-ai-memory-anywhere)
36
34
  - [Available Tools](#available-tools)
37
- - [Real-World Example](#real-world-example)
38
- - [Rust Compiler (n2c)](#rust-compiler-n2c)
39
35
  - [Configuration](#configuration)
40
- - [N2 Ecosystem](#-n2-ecosystem)
41
36
  - [Contributing](#contributing)
42
- - [Sponsors](#-sponsors)
37
+ - [Changelog](CHANGELOG.md)
43
38
 
44
- ## What's New in v8.0
39
+ ## What's New in v9.0
45
40
 
46
- > **Forgetting Curve β€” Soul now remembers what matters and forgets what doesn't.**
41
+ > **Strict TypeScript β€” Zero `any`, zero memory leaks, automated quality enforcement.**
47
42
 
48
- ### 🧠 Intelligent Memory (Forgetting Curve GC)
43
+ ### πŸ”’ Full TypeScript Strict Mode
49
44
 
50
- Inspired by Ebbinghaus' forgetting curve, Soul v8.0 intelligently manages memory retention:
45
+ - Source code migrated to TypeScript with `strict: true`
46
+ - **Zero `any`** β€” every type is explicit and verifiable
47
+ - ESLint `strictTypeChecked` rules catch floating promises, type safety violations
48
+ - 30 unit tests with `npm run verify` one-command pipeline
51
49
 
52
- ```
53
- retention = importance Γ— (1 + logβ‚‚(1 + accessCount)) Γ— e^(βˆ’Ξ» Γ— ageDays)
54
- ```
55
-
56
- - **Frequently accessed** sessions are kept longer
57
- - **Important** snapshots resist decay
58
- - **Stale** memory is automatically pruned via 3-tier lifecycle:
59
-
60
- | Tier | Age | Storage |
61
- |------|-----|--------|
62
- | πŸ”΄ Hot | 0–7 days | In-memory cache + disk |
63
- | 🟑 Warm | 8–30 days | Disk only |
64
- | πŸ”΅ Cold | 30+ days | Archived (compressed) |
65
-
66
- ### ⚑ Performance Revolution β€” Async I/O
67
-
68
- All hot-path I/O operations are now fully asynchronous:
50
+ ### πŸ›‘οΈ Security & Memory Audit
69
51
 
70
- | Operation | v7 (sync) | v8 (async) | Improvement |
71
- |-----------|-----------|------------|-------------|
72
- | KV Save | Blocks event loop | Non-blocking | ∞ (no block) |
73
- | KV Load | 1.2ms (blocking) | 0.7ms (async) | 42% faster |
74
- | KV Search | Blocks | Parallel | 3x+ throughput |
75
- | GC | Blocks during sweep | Background | Non-disruptive |
52
+ - WASM memory leak fix β€” `stmt.free()` wrapped in `try/finally`
53
+ - Silent error swallowing eliminated β€” all `.catch()` handlers log errors
54
+ - HTTP response size limits for embedding requests
55
+ - `dispose()` methods for proper timer cleanup
76
56
 
77
- ### πŸ”§ SDK Native Migration
57
+ ### 🧠 v8.0 Features (Included)
78
58
 
79
- - Removed legacy `registerTool` shim β†’ direct `server.tool()` API
80
- - Strict schema validation: `z.any()` eliminated from all tool definitions
81
- - Full MCP SDK v1.6.1 compatibility
59
+ - **Forgetting Curve GC** β€” intelligent memory retention based on access patterns
60
+ - **Async I/O** β€” non-blocking operations, 42% faster KV load
61
+ - **3-tier memory** β€” Hot β†’ Warm β†’ Cold lifecycle
82
62
 
83
- ### πŸ“¦ Schema v2 (Backward Compatible)
84
-
85
- Snapshots now include Forgetting Curve metadata. Existing v1 snapshots are **auto-migrated** on first load:
86
-
87
- ```diff
88
- + accessCount: 0 // How often this snapshot was accessed
89
- + lastAccessed: null // When it was last loaded
90
- + importance: 0.5 // 0.0–1.0 importance score
91
- + tier: 'warm' // hot / warm / cold
92
- ```
93
-
94
- > [!NOTE]
95
- > **Upgrading from v7.x**: Zero breaking changes. All existing data works as-is. Snapshots are transparently migrated to schema v2 on first access.
63
+ > See [CHANGELOG.md](CHANGELOG.md) for full version history.
96
64
 
97
65
  ---
98
66
 
@@ -0,0 +1 @@
1
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ // Soul MCP v9.0 β€” Entry point. Multi-agent session orchestrator with KV-Cache.
7
+ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
8
+ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
9
+ const zod_1 = require("zod");
10
+ const config_1 = __importDefault(require("./lib/config"));
11
+ const boot_1 = require("./sequences/boot");
12
+ const work_1 = require("./sequences/work");
13
+ const end_1 = require("./sequences/end");
14
+ const brain_1 = require("./tools/brain");
15
+ const kv_cache_1 = require("./tools/kv-cache");
16
+ const package_json_1 = __importDefault(require("../package.json"));
17
+ const server = new mcp_js_1.McpServer({ name: 'n2-soul', version: package_json_1.default.version });
18
+ // Register core modules
19
+ (0, boot_1.registerBootSequence)(server, zod_1.z, config_1.default);
20
+ (0, work_1.registerWorkSequence)(server, zod_1.z, config_1.default);
21
+ (0, end_1.registerEndSequence)(server, zod_1.z, config_1.default);
22
+ (0, brain_1.registerBrainTools)(server, zod_1.z, config_1.default);
23
+ (0, kv_cache_1.registerKVCacheTools)(server, zod_1.z, config_1.default);
24
+ // Start MCP transport
25
+ async function boot() {
26
+ const transport = new stdio_js_1.StdioServerTransport();
27
+ await server.connect(transport);
28
+ }
29
+ boot().catch((err) => {
30
+ console.error(`[n2-soul] Fatal: ${err.message}`);
31
+ process.exit(1);
32
+ });
33
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAAA,+EAA+E;AAC/E,oEAAoE;AACpE,wEAAiF;AACjF,6BAAwB;AAExB,0DAAkC;AAClC,2CAAwD;AACxD,2CAAwD;AACxD,yCAAsD;AACtD,yCAAmD;AACnD,+CAAwD;AAExD,mEAAkC;AAElC,MAAM,MAAM,GAAG,IAAI,kBAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,sBAAG,CAAC,OAAO,EAAE,CAAkF,CAAC;AAEzJ,wBAAwB;AACxB,IAAA,2BAAoB,EAAC,MAAM,EAAE,OAAC,EAAE,gBAAM,CAAC,CAAC;AACxC,IAAA,2BAAoB,EAAC,MAAM,EAAE,OAAC,EAAE,gBAAM,CAAC,CAAC;AACxC,IAAA,yBAAmB,EAAC,MAAM,EAAE,OAAC,EAAE,gBAAM,CAAC,CAAC;AACvC,IAAA,0BAAkB,EAAC,MAAM,EAAE,OAAC,EAAE,gBAAM,CAAC,CAAC;AACtC,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAC,EAAE,gBAAM,CAAC,CAAC;AAExC,sBAAsB;AACtB,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,KAAK,CAAC,oBAAoB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,186 @@
1
+ export interface SoulBoard {
2
+ project: string;
3
+ updatedAt: string;
4
+ updatedBy: string | null;
5
+ state: BoardState;
6
+ activeWork: Record<string, ActiveWork | null>;
7
+ fileOwnership: Record<string, FileOwnership>;
8
+ decisions: BoardDecision[];
9
+ handoff: Handoff;
10
+ lastLedger: string | null;
11
+ }
12
+ export interface BoardState {
13
+ summary: string;
14
+ version: string;
15
+ health: 'unknown' | 'healthy' | 'degraded' | 'critical';
16
+ }
17
+ export interface ActiveWork {
18
+ task: string;
19
+ since: string;
20
+ files: string[];
21
+ }
22
+ export interface FileOwnership {
23
+ owner: string | null;
24
+ since?: string;
25
+ intent?: string;
26
+ }
27
+ export interface Handoff {
28
+ from: string | null;
29
+ summary: string;
30
+ todo: string[];
31
+ blockers: string[];
32
+ }
33
+ export interface BoardDecision {
34
+ date: string;
35
+ by: string;
36
+ what: string;
37
+ why: string;
38
+ }
39
+ export interface McpToolResult {
40
+ content: Array<{
41
+ type: string;
42
+ text: string;
43
+ }>;
44
+ }
45
+ export interface McpToolServer {
46
+ tool(name: string, description: string, schema: Record<string, unknown>, handler: (args: never) => Promise<McpToolResult>): void;
47
+ }
48
+ export interface LedgerEntry {
49
+ id: string;
50
+ agent: string;
51
+ startedAt: string;
52
+ completedAt: string;
53
+ title: string;
54
+ filesCreated: FileChange[];
55
+ filesModified: FileChange[];
56
+ filesDeleted: FileChange[];
57
+ decisions: string[];
58
+ summary: string;
59
+ }
60
+ export interface FileChange {
61
+ path: string;
62
+ desc: string;
63
+ }
64
+ export interface EntityRecord {
65
+ type: EntityType;
66
+ name: string;
67
+ attributes: Record<string, string | number | boolean | null>;
68
+ createdAt: string;
69
+ updatedAt: string;
70
+ }
71
+ export type EntityType = 'person' | 'hardware' | 'project' | 'concept' | 'place' | 'service';
72
+ export interface CoreMemoryData {
73
+ agent: string;
74
+ updatedAt: string;
75
+ entries: Record<string, string>;
76
+ }
77
+ export interface KVSnapshot {
78
+ id: string;
79
+ projectName: string;
80
+ agentName: string;
81
+ timestamp: string;
82
+ keys: string[];
83
+ context: KVContext;
84
+ accessCount: number;
85
+ lastAccessed: string | null;
86
+ importance: number;
87
+ tier: SnapshotTier;
88
+ }
89
+ export interface KVContext {
90
+ summary: string;
91
+ decisions: string[];
92
+ todo: string[];
93
+ filesCreated: FileChange[];
94
+ filesModified: FileChange[];
95
+ }
96
+ export type SnapshotTier = 'hot' | 'warm' | 'cold';
97
+ export interface FileIndex {
98
+ updatedAt: string;
99
+ tree: Record<string, FileEntry | DirectoryEntry>;
100
+ directories?: Record<string, string>;
101
+ }
102
+ export interface FileEntry {
103
+ desc: string;
104
+ created: string;
105
+ modified: string;
106
+ status: 'active' | 'archived' | 'deleted';
107
+ }
108
+ export interface DirectoryEntry {
109
+ desc: string;
110
+ children: Record<string, FileEntry | DirectoryEntry>;
111
+ }
112
+ export interface SoulConfig {
113
+ SOUL_ROOT: string;
114
+ DATA_DIR: string;
115
+ TIMEZONE: string;
116
+ AGENTS_DIR: string | null;
117
+ LANG: string;
118
+ SEARCH: SearchConfig;
119
+ FILE_TREE: FileTreeConfig;
120
+ WORK: WorkConfig;
121
+ KV_CACHE: KVCacheConfig;
122
+ }
123
+ export interface SearchConfig {
124
+ maxDepth: number;
125
+ minKeywordLength: number;
126
+ previewLength: number;
127
+ recencyBonus: number;
128
+ defaultMaxResults: number;
129
+ semanticEnabled: boolean;
130
+ semanticWeight: number;
131
+ }
132
+ export interface FileTreeConfig {
133
+ hidePaths: string[];
134
+ compactPaths: string[];
135
+ childLimit: number;
136
+ }
137
+ export interface WorkConfig {
138
+ sessionTtlHours: number;
139
+ maxDecisions: number;
140
+ }
141
+ export interface KVCacheConfig {
142
+ enabled: boolean;
143
+ autoSaveOnWorkEnd: boolean;
144
+ autoLoadOnBoot: boolean;
145
+ backend: 'json' | 'sqlite';
146
+ maxSnapshotsPerProject: number;
147
+ maxSnapshotAgeDays: number;
148
+ compressionTarget: number;
149
+ snapshotDir: string | null;
150
+ sqliteDir: string | null;
151
+ tokenBudget: TokenBudgetConfig;
152
+ tier: TierConfig;
153
+ embedding: EmbeddingConfig;
154
+ backup: BackupConfig;
155
+ }
156
+ export interface TokenBudgetConfig {
157
+ bootContext: number;
158
+ searchResult: number;
159
+ progressiveLoad: boolean;
160
+ }
161
+ export interface TierConfig {
162
+ hotDays: number;
163
+ warmDays: number;
164
+ }
165
+ export interface EmbeddingConfig {
166
+ enabled: boolean;
167
+ model: string;
168
+ endpoint?: string | null;
169
+ }
170
+ export interface BackupConfig {
171
+ enabled: boolean;
172
+ dir?: string | null;
173
+ schedule: 'manual' | 'daily' | 'weekly';
174
+ keepCount: number;
175
+ incremental: boolean;
176
+ }
177
+ export interface ClaimResult {
178
+ ok: boolean;
179
+ owner?: string;
180
+ intent?: string;
181
+ }
182
+ export interface ProjectInfo {
183
+ name: string;
184
+ updatedAt: string;
185
+ board: SoulBoard;
186
+ }
package/dist/types.js ADDED
@@ -0,0 +1,4 @@
1
+ "use strict";
2
+ // Soul v9.0 β€” Central type definitions for all modules.
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,wDAAwD"}
package/package.json CHANGED
@@ -1,10 +1,19 @@
1
1
  {
2
2
  "name": "n2-soul",
3
- "version": "8.0.0",
3
+ "version": "9.0.1",
4
4
  "description": "AI agent memory & session orchestrator for MCP β€” persistent KV-Cache, Soul Board, immutable Ledger",
5
- "main": "index.js",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
6
7
  "scripts": {
7
- "start": "node index.js"
8
+ "build": "tsc",
9
+ "start": "node dist/index.js",
10
+ "dev": "tsc --watch",
11
+ "typecheck": "tsc --noEmit",
12
+ "lint": "eslint src/",
13
+ "lint:fix": "eslint src/ --fix",
14
+ "test": "node --test dist/tests/*.test.js",
15
+ "verify": "npm run typecheck && npm run build && npm run test",
16
+ "prepublishOnly": "npm run build"
8
17
  },
9
18
  "keywords": [
10
19
  "mcp",
@@ -19,7 +28,7 @@
19
28
  "persistent-memory",
20
29
  "ai-safety",
21
30
  "safety",
22
- "n2-ark"
31
+ "typescript"
23
32
  ],
24
33
  "license": "SEE LICENSE IN LICENSE",
25
34
  "homepage": "https://nton2.com",
@@ -40,5 +49,13 @@
40
49
  "sql.js": "~1.11.0",
41
50
  "sqlite-vec": "^0.1.7",
42
51
  "zod": "~3.24.1"
52
+ },
53
+ "devDependencies": {
54
+ "@eslint/js": "^10.0.1",
55
+ "@types/better-sqlite3": "^7.6.13",
56
+ "@types/node": "^22.19.15",
57
+ "eslint": "^10.1.0",
58
+ "typescript": "^5.9.3",
59
+ "typescript-eslint": "^8.57.2"
43
60
  }
44
61
  }
@@ -1,3 +0,0 @@
1
- # Soul MCP β€” Funding configuration
2
- # This enables the πŸ’– Sponsor button on the GitHub repository
3
- github: [choihyunsus]