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.
- package/CHANGELOG.md +103 -0
- package/README.ko.md +30 -17
- package/README.md +20 -52
- package/dist/index.d.ts +1 -0
- package/dist/index.js +33 -0
- package/dist/index.js.map +1 -0
- package/dist/types.d.ts +186 -0
- package/dist/types.js +4 -0
- package/dist/types.js.map +1 -0
- package/package.json +21 -4
- package/.github/FUNDING.yml +0 -3
- package/CONTRIBUTING.md +0 -142
- package/docs/soul-notebooklm-source.md +0 -127
- package/docs/soul-v8-roadmap.md +0 -152
- package/index.js +0 -38
- package/lib/agent-registry.js +0 -60
- package/lib/config.default.js +0 -84
- package/lib/config.example.js +0 -28
- package/lib/config.js +0 -28
- package/lib/context.js +0 -34
- package/lib/core-memory.js +0 -137
- package/lib/entity-memory.js +0 -219
- package/lib/intercom-log.js +0 -187
- package/lib/kv-cache/agent-adapter.js +0 -192
- package/lib/kv-cache/backup.js +0 -357
- package/lib/kv-cache/compressor.js +0 -130
- package/lib/kv-cache/embedding.js +0 -205
- package/lib/kv-cache/index.js +0 -400
- package/lib/kv-cache/schema.js +0 -124
- package/lib/kv-cache/snapshot.js +0 -320
- package/lib/kv-cache/sqlite-store.js +0 -402
- package/lib/kv-cache/tier-manager.js +0 -248
- package/lib/kv-cache/token-saver.js +0 -153
- package/lib/paths.js +0 -29
- package/lib/soul-engine.js +0 -234
- package/lib/utils.js +0 -167
- package/sequences/boot.js +0 -127
- package/sequences/end.js +0 -157
- package/sequences/work.js +0 -260
- package/tests/README.md +0 -5
- package/tests/test-simulation.js +0 -153
- package/tools/brain.js +0 -122
- 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
|
-
- π·οΈ **μν°ν° λ©λͺ¨λ¦¬** β μΈλ¬Ό, νλμ¨μ΄, νλ‘μ νΈλ₯Ό μλ μΆμ ν©λλ€
|
|
26
|
-
- π‘ **μ½μ΄ λ©λͺ¨λ¦¬** β μμ΄μ νΈλ³ ν΅μ¬ μ¬μ€μ΄ νμ λ‘λλ©λλ€
|
|
27
|
-
- π‘οΈ **Ark** β ν ν° λΉμ© 0μΌλ‘ μνν νλμ μ°¨λ¨νλ AI μμ μμ€ν
(v6.0)
|
|
28
|
-
- πΈοΈ **Arachne** β AIμκ² μ νν νμν μ½λλ§ μ λ¬νλ μ½λ 컨ν
μ€νΈ μμ§ (v7.0)
|
|
13
|
+
- π·οΈ **μν°ν° λ©λͺ¨λ¦¬** β μΈλ¬Ό, νλμ¨μ΄, νλ‘μ νΈλ₯Ό μλ μΆμ ν©λλ€
|
|
14
|
+
- π‘ **μ½μ΄ λ©λͺ¨λ¦¬** β μμ΄μ νΈλ³ ν΅μ¬ μ¬μ€μ΄ νμ λ‘λλ©λλ€
|
|
29
15
|
|
|
30
|
-
>
|
|
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)
|
|
7
7
|
[](https://nodejs.org)
|
|
8
8
|
[](https://www.npmjs.com/package/n2-soul)
|
|
9
|
-
[](#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
|
|
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
|
-
- [
|
|
37
|
+
- [Changelog](CHANGELOG.md)
|
|
43
38
|
|
|
44
|
-
## What's New in
|
|
39
|
+
## What's New in v9.0
|
|
45
40
|
|
|
46
|
-
> **
|
|
41
|
+
> **Strict TypeScript β Zero `any`, zero memory leaks, automated quality enforcement.**
|
|
47
42
|
|
|
48
|
-
###
|
|
43
|
+
### π Full TypeScript Strict Mode
|
|
49
44
|
|
|
50
|
-
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
###
|
|
57
|
+
### π§ v8.0 Features (Included)
|
|
78
58
|
|
|
79
|
-
-
|
|
80
|
-
-
|
|
81
|
-
-
|
|
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
|
-
|
|
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
|
|
package/dist/index.d.ts
ADDED
|
@@ -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"}
|
package/dist/types.d.ts
ADDED
|
@@ -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 @@
|
|
|
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": "
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
}
|
package/.github/FUNDING.yml
DELETED