n2-soul 5.0.1 → 6.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to Soul
+
+Thank you for your interest in contributing to Soul! 🧠
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- Git
+
+### Setup
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/soul.git
+   cd soul
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Test your setup:
+   ```bash
+   node index.js
+   ```
+   You should see the MCP server start without errors (it will wait for stdin input).
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Open an [issue](https://github.com/choihyunsus/soul/issues) with `[Bug]` in the title
+- Include: Node.js version, OS, MCP client (Cursor/VS Code/etc.), and steps to reproduce
+- If possible, include the relevant Soul Board or Ledger output
+
+### Suggesting Features
+
+- Open an [issue](https://github.com/choihyunsus/soul/issues) with `[Feature]` in the title
+- Describe the use case and expected behavior
+- Bonus: include a rough API design
+
+### Submitting Code
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/amazing-feature
+   ```
+2. Make your changes
+3. Test manually with your MCP client
+4. Commit with [Conventional Commits](https://www.conventionalcommits.org/):
+   ```bash
+   git commit -m 'feat: add amazing feature'
+   ```
+5. Push and open a Pull Request:
+   ```bash
+   git push origin feature/amazing-feature
+   ```
+
+## Code Guidelines
+
+### Project Structure
+
+```
+soul/
+├── index.js              # Entry point (MCP server setup)
+├── lib/                  # Core libraries
+│   ├── config.js         # Config loader (default + local deep merge)
+│   ├── config.default.js # Default settings (shipped)
+│   ├── soul-engine.js    # Core engine
+│   ├── utils.js          # Shared utilities
+│   └── kv-cache/         # KV-Cache engine (snapshots, compression, search)
+├── sequences/            # Agent lifecycle
+│   ├── boot.js           # n2_boot
+│   ├── work.js           # n2_work_start, n2_work_claim, n2_work_log
+│   └── end.js            # n2_work_end
+├── tools/                # MCP tool registrations
+│   ├── brain.js          # n2_brain_read/write, n2_entity_*, n2_core_*
+│   └── kv-cache.js       # n2_kv_save/load/search/backup/restore/gc
+└── data/                 # Runtime data (gitignored, auto-created)
+```
+
+### Style
+
+- **No build step** — Soul runs directly with Node.js
+- **Minimal dependencies** — Think twice before adding a new package (currently only 3)
+- **CommonJS** — Use `require()` / `module.exports` (not ESM)
+- **Descriptive naming** — Functions and variables should be self-documenting
+- **Error handling** — Always return meaningful error messages to the MCP client
+
+### Adding a New Tool
+
+1. Create or edit a file in `tools/`
+2. Register the tool using the MCP SDK pattern:
+   ```js
+   server.tool('n2_your_tool', 'Description', { /* zod schema */ }, async (params) => {
+       // implementation
+       return { content: [{ type: 'text', text: 'result' }] };
+   });
+   ```
+3. If it's a new file, import and register it in `index.js`
+
+### Adding a New Sequence
+
+1. Create or edit a file in `sequences/`
+2. Follow the existing pattern in `boot.js` / `work.js` / `end.js`
+3. Register in `index.js`
+
+## Testing
+
+Soul doesn't have a formal test suite yet — this is a great area to contribute!
+
+Currently, testing is done by:
+1. Starting Soul as an MCP server
+2. Connecting from an MCP client (Cursor, VS Code, etc.)
+3. Calling tools and verifying output
+
+## Pull Request Guidelines
+
+- **One feature per PR** — keep PRs focused and reviewable
+- **Update README** if you add/change tools or features
+- **No breaking changes** without discussion in an issue first
+- **Keep dependencies minimal** — justify any new package
+
+## Architecture Principles
+
+- **Deterministic over probabilistic** — Soul forces saves/loads instead of relying on LLM decisions
+- **Zero config by default** — Everything should work with just `node index.js`
+- **Progressive complexity** — Simple for beginners, powerful for advanced users
+- **Multi-agent first** — Every feature should consider concurrent agent scenarios
+
+## Community
+
+- 🌐 [nton2.com](https://nton2.com)
+- 📦 [npm](https://www.npmjs.com/package/n2-soul)
+- 🐛 [Issues](https://github.com/choihyunsus/soul/issues)
+- ✉️ lagi0730@gmail.com
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](LICENSE).

package/README.ko.md

@@ -3,6 +3,18 @@
 # 🧠 Soul
 
 **AI 에이전트는 세션이 끝나면 모든 걸 잊어버립니다. Soul이 그걸 해결합니다.**
+**AI 에이전트가 위험한 행동을 할 수도 있습니다. Ark가 그걸 막습니다.**
+
+> ### 🚀 v6.0 업데이트 — Ark: 최후의 방패
+>
+> Soul v6.0에 **Ark**가 탑재되었습니다. 모든 도구 호출을 검사하고 위험한 행동을 **실행 전에** 차단하는 AI 안전 시스템입니다. LLM 호출 없음, 토큰 비용 0, 지연 없음 — MCP 서버 레벨의 순수 정규식 매칭.
+>
+> - 모든 도구 호출이 `ark.check()`를 통과 — **무조건**
+> - `enabled: false` 옵션 없음 — Ark는 항상 켜져 있음 (의도적 설계)
+> - 12개 블랙리스트 규칙, 125개 패턴, 7개 업종별 템플릿 포함
+> - 자기보호: 4계층으로 AI가 방화벽을 비활성화하는 것을 방지
+>
+> v6.0이 **메이저 버전**인 이유: 모든 도구 호출에 수호자가 생겼습니다. [자세히 →](#ark--최후의-방패)
 
 Cursor, VS Code Copilot 등 MCP 호환 AI 에이전트와 새 채팅을 시작할 때마다, 에이전트는 이전에 뭘 했는지 전혀 모른 채 처음부터 시작합니다. Soul은 에이전트에게 이런 능력을 부여하는 MCP 서버입니다:
 
@@ -12,6 +24,7 @@ Cursor, VS Code Copilot 등 MCP 호환 AI 에이전트와 새 채팅을 시작
 - 🗂️ **공유 두뇌** — 여러 에이전트가 같은 컨텍스트를 읽고 쓸 수 있습니다
 - 🏷️ **엔티티 메모리** — 인물, 하드웨어, 프로젝트를 자동 추적합니다 (v5.0)
 - 💡 **코어 메모리** — 에이전트별 핵심 사실이 항상 로드됩니다 (v5.0)
+- 🛡️ **Ark** — 토큰 비용 0으로 위험한 행동을 차단하는 AI 안전 시스템 (v6.0)
 
 > ⚡ **Soul은 N2 Browser의 작은 부속품 하나입니다** — 우리가 만들고 있는 AI 네이티브 브라우저의 일부예요. 멀티 에이전트 오케스트레이션, 실시간 도구 라우팅, 에이전트 간 통신 등 훨씬 더 많은 기능들이 현재 테스트 중입니다. 이건 시작에 불과합니다.
 
@@ -127,6 +140,55 @@ n2_work_end(project, title, summary, todo, entities, insights)
 | **듀얼 백엔드** | JSON (의존성 없음) 또는 SQLite (고성능) |
 | **시맨틱 검색** | Ollama 임베딩 연동 (nomic-embed-text, 선택사항) |
 | **백업/복원** | 설정 가능한 보존 기간의 증분 백업 |
+| **Ark** | 토큰 비용 0으로 위험한 행동을 차단하는 AI 안전 시스템 (v6.0) |
+
+## Ark — 최후의 방패
+
+![Ark Comic](docs/ark-comic.png)
+
+노아의 방주처럼 — 대홍수에서 살아남는 최후의 보루.
+
+### 왜 Ark인가?
+
+| | Ark | LLM 기반 안전 | 임베딩 기반 |
+|---|:---:|:---:|:---:|
+| **토큰 비용** | 0 | 검사당 500~2,000 | 검사당 100~500 |
+| **지연** | < 1ms | 1~5초 | 200~500ms |
+| **추가 의존성** | 0 (순수 JS) | LLM API 키 필요 | 벡터 DB 필요 |
+| **오프라인 작동** | 가능 | 불가 | 경우에 따라 |
+| **항상 활성화** | 필수 (토글 없음) | 선택적 | 선택적 |
+| **자기보호** | 4계층 대응 | 없음 | 없음 |
+| **규칙 형식** | `.n2` 파일 (사람이 읽을 수 있음) | 프롬프트 엔지니어링 | 임베딩 튜닝 |
+| **업종별 템플릿** | 7개 도메인 포함 | 직접 작성 | 직접 작성 |
+| **MCP 호환** | 모든 호스트 (Cursor, VS Code, Claude Desktop) | 호스트 한정 | 호스트 한정 |
+
+### 토큰 비용: 0
+
+**왜 0인가?** Ark는 AI 모델 안이 아니라 **MCP 서버 내부(Node.js)에서** 실행되기 때문입니다.
+
+```
+┌───────────────────────────────────────┐
+│           LLM (클라우드)              │
+│    AI 에이전트가 도구 호출 생성      │
+│       (토큰이 사용되는 곳)           │
+└───────────────────┬───────────────────┘
+                    │ 도구 호출
+                    ▼
+┌───────────────────────────────────────┐
+│    MCP 서버 (Node.js, 로컬)         │
+│                                       │
+│   ark.check() ← 순수 정규식, 여기서 실행 │
+│   < 1ms         네트워크/LLM/토큰 없음  │
+│                                       │
+│   통과? ─No─▶ "BLOCKED" 텍스트 반환    │
+│     │                                 │
+│    Yes ─▶ 핸들러 실행                  │
+└───────────────────────────────────────┘
+```
+
+핵심: **토큰 비용은 LLM 내부에서만 발생**합니다. Ark는 한 단계 아래 — 서버 레벨에 있습니다. LLM이 도구 호출을 보내면, Ark가 핸들러 실행 전에 정규식으로 검사합니다. 두 번째 LLM 호출 없음, API 요청 없음, 벡터 검색 없음. 그냥 문자열 매칭.
+
+세션당 100회 도구 호출 기준, LLM 기반 안전 대비 **50,000~200,000 토큰 절감**.
 
 ## 사용 가능한 도구
 
@@ -189,25 +251,43 @@ module.exports = {
 모든 런타임 데이터는 `data/`에 저장됩니다 (gitignored, 자동 생성):
 
 ```
-data/
-├── memory/              # 공유 두뇌 (n2_brain_read/write)
-│   ├── entities.json    # 엔티티 메모리 (자동 추적)        ← NEW v5.0
-│   ├── core-memory/     # 코어 메모리 (에이전트별 사실)    ← NEW v5.0
-│   │   └── {agent}.json
-│   └── auto-extract/    # 인사이트 (자동 캡처)             ← NEW v5.0
-│       └── {project}/
-├── projects/            # 프로젝트별 상태
-│   └── MyProject/
-│       ├── soul-board.json    # 현재 상태 + 인수인계
-│       ├── file-index.json    # 파일 트리 스냅샷
-│       └── ledger/            # 변경 불가능한 작업 로그
-│           └── 2026/03/09/
-│               └── 001-agent.json
-└── kv-cache/            # 세션 스냅샷
-    ├── snapshots/       # JSON 백엔드
-    ├── sqlite/          # SQLite 백엔드
-    ├── embeddings/      # Ollama 벡터
-    └── backups/         # 이동 가능한 백업
+soul/
+├── rules/              # Ark 안전 규칙 (활성)               ← NEW v6.0
+│   └── default.n2          # 기본 규칙셋 (125개 패턴)
+├── lib/
+│   └── ark/            # Ark 코어 엔진                     ← NEW v6.0
+│       ├── index.js        # createArk() 팩토리
+│       ├── gate.js         # SafetyGate 엔진
+│       ├── parser.js       # .n2 규칙 파서
+│       ├── audit.js        # 감사 로거
+│       └── examples/       # 업종별 규칙 템플릿
+│           ├── medical.n2       # 의료 (HIPAA, 처방)
+│           ├── military.n2      # 군사 (교전, 핵)
+│           ├── financial.n2     # 금융 (결제, 거래)
+│           ├── legal.n2         # 법률 (계약, 소송)
+│           ├── privacy.n2       # 개인정보 (GDPR, CCPA)
+│           ├── autonomous.n2    # 자율주행 (드론, 차량)
+│           └── system.n2        # 시스템 (배포, 인프라)
+├── data/
+│   ├── memory/              # 공유 두뇌 (n2_brain_read/write)
+│   │   ├── entities.json    # 엔티티 메모리 (자동 추적)
+│   │   ├── core-memory/     # 코어 메모리 (에이전트별)
+│   │   │   └── {agent}.json
+│   │   └── auto-extract/    # 인사이트 (자동 캡처)
+│   │       └── {project}/
+│   ├── projects/            # 프로젝트별 상태
+│   │   └── MyProject/
+│   │       ├── soul-board.json    # 현재 상태 + 인수인계
+│   │       ├── file-index.json    # 파일 트리 스냅샷
+│   │       └── ledger/            # 변경 불가능한 작업 로그
+│   │           └── 2026/03/09/
+│   │               └── 001-agent.json
+│   ├── ark-audit/           # Ark 차단/통과 로그          ← NEW v6.0
+│   └── kv-cache/            # 세션 스냅샷
+│       ├── snapshots/       # JSON 백엔드
+│       ├── sqlite/          # SQLite 백엔드
+│       ├── embeddings/      # Ollama 벡터
+│       └── backups/         # 이동 가능한 백업
 ```
 
 ## 의존성