n2-soul 7.0.0 → 7.0.1

package/README.ko.md

@@ -4,14 +4,15 @@
 
 **AI 에이전트는 세션이 끝나면 모든 걸 잊어버립니다. Soul이 그걸 해결합니다.**
 **AI 에이전트가 위험한 행동을 할 수도 있습니다. Ark가 그걸 막습니다.**
+**AI 에이전트가 관련 없는 코드를 읽느라 토큰을 낭비합니다. Arachne가 그걸 해결합니다.**
 
-> ### 🚀 v6.1 업데이트 — 클라우드 저장
+> ### 🚀 v7.0 업데이트 — Arachne
 >
-> AI 기억을 **어디에든** 저장하세요 — Google Drive, OneDrive, NAS, 회사 서버, USB. 설정 한 줄이면 끝:
-> ```js
-> DATA_DIR: 'G:/내 드라이브/n2-soul'
+> **Arachne** — 코드 컨텍스트 어셈블리 엔진. 코드베이스 전체를 인덱싱하고 AI에게 **정확히** 필요한 것만 전달합니다.
 > ```
-> **월 $0. API 키 없음. 새 의존성 없음.** Soul은 기존 파일 동기화를 활용합니다. [자세히 →](#️-클라우드-저장--ai-기억을-원하는-곳-어디에든)
+> 50,000 파일 프로젝트 → 가장 관련 있는 30개 청크 → 30K 토큰 (500K+ 대신)
+> ```
+> BM25 검색 + 의존성 추적 + 스마트 어셈블리. Ollama를 통한 시맨틱 검색도 지원. [자세히 →](#arachne--최고의-직조사)
 >
 > **Ark** (v6.0) 포함 — 토큰 비용 0으로 위험한 행동을 차단하는 AI 안전 시스템. [자세히 →](#ark--최후의-방패)
 
@@ -24,6 +25,7 @@ Cursor, VS Code Copilot 등 MCP 호환 AI 에이전트와 새 채팅을 시작
 - 🏷️ **엔티티 메모리** — 인물, 하드웨어, 프로젝트를 자동 추적합니다 (v5.0)
 - 💡 **코어 메모리** — 에이전트별 핵심 사실이 항상 로드됩니다 (v5.0)
 - 🛡️ **Ark** — 토큰 비용 0으로 위험한 행동을 차단하는 AI 안전 시스템 (v6.0)
+- 🕸️ **Arachne** — AI에게 정확히 필요한 코드만 전달하는 코드 컨텍스트 엔진 (v7.0)
 
 > ⚡ **Soul은 N2 Browser의 작은 부속품 하나입니다** — 우리가 만들고 있는 AI 네이티브 브라우저의 일부예요. 멀티 에이전트 오케스트레이션, 실시간 도구 라우팅, 에이전트 간 통신 등 훨씬 더 많은 기능들이 현재 테스트 중입니다. 이건 시작에 불과합니다.
 
@@ -206,6 +208,7 @@ n2_work_end(project, title, summary, todo, entities, insights)
 | **시맨틱 검색** | Ollama 임베딩 연동 (nomic-embed-text, 선택사항) |
 | **백업/복원** | 설정 가능한 보존 기간의 증분 백업 |
 | **Ark** | 토큰 비용 0으로 위험한 행동을 차단하는 AI 안전 시스템 (v6.0) |
+| **🕸️ Arachne** | 🆕 코드 컨텍스트 어셈블리 — 코드베이스를 인덱싱하고 AI에게 필요한 것만 전달 (v7.0) |
 | **☁️ 클라우드 저장** | 기억을 어디에든 저장 — Google Drive, NAS, 회사 서버, 아무 경로나 (v6.1) |
 
 ## ☁️ 클라우드 저장 — AI 기억을 원하는 곳 어디에든
@@ -356,6 +359,7 @@ Soul의 데이터는 모두 '일반 파일'이므로, OS 기본 기능(크론탭
 | `n2_kv_backup` | SQLite DB로 백업 |
 | `n2_kv_restore` | 백업에서 복원 |
 | `n2_kv_backup_list` | 백업 이력 조회 |
+| `n2_arachne` | 🆕 코드 컨텍스트: 인덱싱, 검색, 어셈블, 백업, 상태 (v7.0) |
 
 ## KV-Cache 점진적 로딩
 
@@ -403,22 +407,23 @@ module.exports = {
 
 ```
 soul/
-├── rules/              # Ark 안전 규칙 (활성)               ← NEW v6.0
+├── rules/              # Ark 안전 규칙 (활성)               ← 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        # 시스템 (배포, 인프라)
+│   ├── ark/            # Ark 코어 엔진                     ← v6.0
+│   │   ├── index.js        # createArk() 팩토리
+│   │   ├── gate.js         # SafetyGate 엔진
+│   │   ├── parser.js       # .n2 규칙 파서
+│   │   ├── audit.js        # 감사 로거
+│   │   └── examples/       # 업종별 규칙 템플릿
+│   └── arachne/        # Arachne 코드 컨텍스트 엔진        ← NEW v7.0
+│       ├── index.js        # createArachne() 팩토리
+│       ├── indexer.js      # 파일 스캐너 + 증분 인덱싱
+│       ├── chunker.js      # 언어 인식 코드 청킹
+│       ├── search.js       # BM25 검색 엔진
+│       ├── assembler.js    # 토큰 예산 기반 컨텍스트 어셈블리
+│       ├── store.js        # SQLite 저장 (sql.js)
+│       └── ignore.js       # .gitignore + .contextignore 지원
 ├── data/
 │   ├── memory/              # 공유 두뇌 (n2_brain_read/write)
 │   │   ├── entities.json    # 엔티티 메모리 (자동 추적)
@@ -433,7 +438,8 @@ soul/
 │   │       └── ledger/            # 변경 불가능한 작업 로그
 │   │           └── 2026/03/09/
 │   │               └── 001-agent.json
-│   ├── ark-audit/           # Ark 차단/통과 로그          ← NEW v6.0
+│   ├── ark-audit/           # Ark 차단/통과 로그          ← v6.0
+│   ├── arachne/             # Arachne 인덱스 DB + 임베딩  ← NEW v7.0
 │   └── kv-cache/            # 세션 스냅샷
 │       ├── snapshots/       # JSON 백엔드
 │       ├── sqlite/          # SQLite 백엔드

package/README.md

@@ -6,18 +6,19 @@
 [![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)
-[![NEW](https://img.shields.io/badge/v6.1-Cloud%20Storage-4488ff?style=for-the-badge)](https://github.com/choihyunsus/soul#️-cloud-storage--store-your-ai-memory-anywhere)
+[![NEW](https://img.shields.io/badge/v7.0-Arachne-9944ff?style=for-the-badge)](https://github.com/choihyunsus/soul#arachne--the-greatest-weaver)
 
 **Your AI agent forgets everything when a session ends. Soul fixes that.**
 **Your AI agent might do something dangerous. Ark stops that.**
+**Your AI agent wastes tokens reading irrelevant code. Arachne fixes that.**
 
-> ### 🚀 What's New in v6.1 — Cloud Storage
+> ### 🚀 What's New in v7.0 — Arachne
 >
-> Store your AI memory **anywhere** — Google Drive, OneDrive, NAS, company server, USB. Just one line:
-> ```js
-> DATA_DIR: 'G:/My Drive/n2-soul'
+> **Arachne** — Code Context Assembly Engine. Indexes your entire codebase and picks **exactly** what your AI needs.
 > ```
-> **$0/month. Zero API keys. Zero new dependencies.** Soul uses your existing file sync. [Learn more →](#️-cloud-storage--store-your-ai-memory-anywhere)
+> 50,000 file project → 30 most relevant chunks → 30K tokens (instead of 500K+)
+> ```
+> BM25 search + dependency tracking + smart assembly. Optional semantic search via Ollama. [Learn more →](#arachne--the-greatest-weaver)
 >
 > Also includes **Ark** (v6.0) — built-in AI safety that blocks dangerous actions at zero token cost. [Learn more →](#ark--the-last-shield)
 
@@ -30,6 +31,7 @@ Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compati
 - 🏷️ **Entity Memory** — auto-tracks people, hardware, projects (v5.0)
 - 💡 **Core Memory** — agent-specific always-loaded facts (v5.0)
 - 🛡️ **Ark** — built-in AI safety that blocks dangerous actions at zero token cost (v6.0)
+- 🕸️ **Arachne** — code context assembly engine that picks exactly what AI needs (v7.0)
 
 > ⚡ **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.
 
@@ -47,6 +49,7 @@ Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compati
 - [Configuration](#configuration)
 - [Contributing](#contributing)
 - [Ark — The Last Shield](#ark--the-last-shield)
+- [Arachne — The Greatest Weaver](#arachne--the-greatest-weaver)
 
 ## Quick Start
 
@@ -243,6 +246,7 @@ n2_work_end(project, title, summary, todo, entities, insights)
 | **Semantic Search** | Optional Ollama embedding (nomic-embed-text) |
 | **Backup/Restore** | Incremental backups with configurable retention |
 | **Ark** | 🆕 Built-in AI safety — blocks dangerous actions at zero token cost |
+| **Arachne** | 🆕 Code context assembly — indexes codebase, picks exactly what AI needs (v7.0) |
 | **Cloud Storage** | 🆕 Store memory anywhere — Google Drive, NAS, network server, any path (v6.1) |
 
 ## ☁️ Cloud Storage — Store Your AI Memory Anywhere
@@ -536,6 +540,92 @@ module.exports = {
 - **Wildcard destruction** — blocks `rm *`, `find -delete`, `xargs rm` (self-protection bypass)
 - **Command execution gate** — `@gate` on `execute_command`, `run_shell`, etc. (whitelist approach)
 
+## Arachne — The Greatest Weaver
+
+> *In Greek mythology, Arachne was a mortal weaver whose tapestries rivaled the gods. She wove exactly the right threads in exactly the right places.*
+
+**Arachne** is Soul's code context assembly engine. It indexes your entire codebase and picks **exactly** the chunks your AI agent needs — no more, no less.
+
+### The Problem
+
+AI agents waste massive tokens reading irrelevant code:
+
+| Approach | Tokens used | Relevance |
+|----------|:----------:|:---------:|
+| **Paste entire file** | 10,000+ | ~20% relevant |
+| **Dump whole project** | 500,000+ | ~5% relevant |
+| **Arachne** | ~30,000 | **~90% relevant** |
+
+### How Arachne Works
+
+```
+Your 50,000-file project
+         │
+    ┌────┴────┐
+    │  Index   │ ← Scans all files, chunks by function/class
+    │  (boot)  │   Incremental: only re-indexes changed files
+    └────┬────┘
+         │
+    ┌────┴────┐
+    │  Search  │ ← BM25 keyword search (+ optional semantic via Ollama)
+    │  (query) │   Finds the most relevant chunks across all files
+    └────┬────┘
+         │
+    ┌────┴────┐
+    │ Assemble │ ← Picks top chunks within your token budget
+    │ (budget) │   4 layers: fixed + short-term + associative + spare
+    └────┬────┘
+         │
+   30 most relevant
+   code chunks → AI
+```
+
+### Key Features
+
+| Feature | Description |
+|---------|------------|
+| **Incremental Indexing** | Only re-indexes changed files (hash-based detection) |
+| **Language-Aware Chunking** | Splits code by function/class boundaries, not arbitrary lines |
+| **BM25 Search** | Fast keyword search with TF-IDF ranking |
+| **Semantic Search** | Optional Ollama embeddings (nomic-embed-text) |
+| **Token Budget Assembly** | Smart context assembly within configurable token limits |
+| **4-Layer Assembly** | Fixed (10%) + Short-term (30%) + Associative (40%) + Spare (20%) |
+| **17 Languages** | JS, TS, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin |
+| **12 Text Formats** | MD, JSON, YAML, XML, HTML, CSS, SQL, Shell scripts |
+| **Backup/Restore** | Incremental backups with configurable retention |
+
+### Configuration
+
+Arachne settings in `lib/config.default.js`:
+
+```js
+ARACHNE: {
+    projectDir: null,         // Set to your project root to enable
+    indexing: {
+        autoIndex: true,      // Auto-index on boot
+        maxFileSize: 512 * 1024,
+    },
+    assembly: {
+        defaultBudget: 30000, // Token budget for context
+    },
+    embedding: {
+        enabled: false,       // true = requires: ollama pull nomic-embed-text
+    },
+}
+```
+
+### Usage
+
+```
+n2_arachne(action: "index")     → Index your project files
+n2_arachne(action: "search", query: "authentication JWT")  → Search code
+n2_arachne(action: "assemble", query: "how does auth work?", budget: 30000)  → Full context assembly
+n2_arachne(action: "status")    → Check index status
+n2_arachne(action: "backup")    → Backup index DB
+```
+
+> **Also available as standalone package:** [`n2-arachne`](https://www.npmjs.com/package/n2-arachne) — use Arachne without Soul.
+
 ## Available Tools
 
 | Tool | Description |
@@ -559,6 +649,7 @@ module.exports = {
 | `n2_kv_backup` | Backup to portable SQLite DB |
 | `n2_kv_restore` | Restore from backup |
 | `n2_kv_backup_list` | List backup history |
+| `n2_arachne` | 🆕 Code context: index, search, assemble, backup, status (v7.0) |
 
 ## KV-Cache Progressive Loading
 
@@ -676,22 +767,23 @@ All runtime data is stored in `data/` (gitignored, auto-created):
 
 ```
 soul/
-├── rules/              # Ark safety rules (active)              ← NEW v6.0
+├── rules/              # Ark safety rules (active)              ← v6.0
 │   └── default.n2          # Default ruleset (125 patterns)
 ├── lib/
-│   └── ark/            # Ark core engine                        ← NEW v6.0
-│       ├── index.js        # createArk() factory
-│       ├── gate.js         # SafetyGate engine
-│       ├── parser.js       # .n2 rule parser
-│       ├── audit.js        # Audit logger
-│       └── examples/       # Industry rule templates
-│           ├── medical.n2       # Healthcare (HIPAA, prescriptions)
-│           ├── military.n2      # Defense (engagement, nuclear)
-│           ├── financial.n2     # Finance (payments, transactions)
-│           ├── legal.n2         # Legal (contracts, litigation)
-│           ├── privacy.n2       # Privacy (GDPR, CCPA, PII)
-│           ├── autonomous.n2    # Autonomous (drones, vehicles)
-│           └── system.n2        # DevOps (deployment, infra)
+│   ├── ark/            # Ark core engine                        ← v6.0
+│   │   ├── index.js        # createArk() factory
+│   │   ├── gate.js         # SafetyGate engine
+│   │   ├── parser.js       # .n2 rule parser
+│   │   ├── audit.js        # Audit logger
+│   │   └── examples/       # Industry rule templates
+│   └── arachne/        # Arachne code context engine             ← NEW v7.0
+│       ├── index.js        # createArachne() factory
+│       ├── indexer.js      # File scanner + incremental indexing
+│       ├── chunker.js      # Language-aware code chunking
+│       ├── search.js       # BM25 search engine
+│       ├── assembler.js    # Context assembly with token budget
+│       ├── store.js        # SQLite storage (sql.js)
+│       └── ignore.js       # .gitignore + .contextignore support
 ├── data/
 │   ├── memory/         # Shared brain (n2_brain_read/write)
 │   │   ├── entities.json       # Entity Memory (auto-tracked)
@@ -706,7 +798,8 @@ soul/
 │   │       └── ledger/            # Immutable work logs
 │   │           └── 2026/03/09/
 │   │               └── 001-agent.json
-│   ├── ark-audit/      # Ark block/pass logs                   ← NEW v6.0
+│   ├── ark-audit/      # Ark block/pass logs                   ← v6.0
+│   ├── arachne/        # Arachne index DB + embeddings          ← NEW v7.0
 │   └── kv-cache/       # Session snapshots
 │       ├── snapshots/  # JSON backend
 │       ├── sqlite/     # SQLite backend

package/index.js

@@ -77,13 +77,8 @@ async function boot() {
     if (config.ARACHNE?.projectDir) {
         try {
             const arachne = await createArachne({
+                ...config.ARACHNE,
                 dataDir: config.ARACHNE.dataDir ?? path.join(config.DATA_DIR, 'arachne'),
-                projectDir: config.ARACHNE.projectDir,
-                indexing: config.ARACHNE.indexing ?? { autoIndex: true },
-                search: config.ARACHNE.search ?? {},
-                assembly: config.ARACHNE.assembly ?? {},
-                backup: config.ARACHNE.backup ?? {},
-                embedding: config.ARACHNE.embedding ?? {},
             });
             registerArachneTools(server, z, arachne, config);
             console.error(`[n2-soul] Arachne enabled: ${config.ARACHNE.projectDir}`);

package/lib/arachne/chunker.js

@@ -1,12 +1,27 @@
 // chunker.js — Split source code into function/class-level chunks
 // Phase 1: Regex-based (no parser needed), Phase 2: AST replacement possible
 
+// Default: ~3.5 chars/token for English code
+// CJK (Korean/Chinese/Japanese): ~1.5 chars/token (set via config)
+let _tokenMultiplier = 3.5;
+
+/**
+ * Set token multiplier (called from config)
+ * @param {number|object} multiplier — number (global) or {default, ko, zh, ja} per-language
+ */
+function setTokenMultiplier(multiplier) {
+    if (typeof multiplier === 'number' && multiplier > 0) {
+        _tokenMultiplier = multiplier;
+    }
+}
+
 /**
- * Estimate token count (approximate — without exact tokenizer)
- * Code average: ~3.5 characters = 1 token
+ * Estimate token count (configurable via tokenMultiplier)
+ * @param {string} text
+ * @param {string} [language] — optional language hint for per-language multiplier
  */
-function estimateTokens(text) {
-    return Math.ceil(text.length / 3.5);
+function estimateTokens(text, language) {
+    return Math.ceil(text.length / _tokenMultiplier);
 }
 
 // Language-specific chunk detection patterns
@@ -235,4 +250,4 @@ function detectLanguage(filePath) {
     return ext;
 }
 
-module.exports = { chunkCode, estimateTokens, detectLanguage, LANG_MAP, CHUNK_PATTERNS };
+module.exports = { chunkCode, estimateTokens, detectLanguage, setTokenMultiplier, LANG_MAP, CHUNK_PATTERNS };

package/lib/arachne/indexer.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { IgnoreFilter } = require('./ignore');
-const { chunkCode, detectLanguage } = require('./chunker');
+const { chunkCode, detectLanguage, setTokenMultiplier } = require('./chunker');
 const { indexFileDependencies } = require('./dependency');
 
 class Indexer {
@@ -15,6 +15,11 @@ class Indexer {
         this._store = store;
         this._config = config;
         this._ignoreFilter = null;
+
+        // Apply token multiplier from config
+        if (config.indexing?.tokenMultiplier) {
+            setTokenMultiplier(config.indexing.tokenMultiplier);
+        }
     }
 
     /**

package/lib/config.default.js

@@ -93,11 +93,39 @@ module.exports = {
         dataDir: null,                  // null = DATA_DIR/arachne/
         indexing: {
             autoIndex: true,            // Auto-index on boot
+            incremental: true,
             maxFileSize: 512 * 1024,    // 512KB max per file
+            maxFiles: 50000,
+            chunkStrategy: 'regex',
+            tokenMultiplier: 3.5,       // Chars per token. English/code: 3.5, CJK: 1.5
+            supportedLanguages: ['js', 'ts', 'jsx', 'tsx', 'py', 'rs', 'go', 'java', 'c', 'cpp', 'h', 'hpp', 'cs', 'rb', 'php', 'swift', 'kt'],
+            alsoIndexAsText: ['md', 'json', 'yaml', 'yml', 'toml', 'xml', 'html', 'css', 'sql', 'sh', 'bat', 'ps1'],
+        },
+        ignore: {
+            useGitignore: true,
+            useContextignore: true,
+            patterns: [
+                'node_modules/**', 'vendor/**', '__pycache__/**', '.venv/**',
+                'dist/**', 'build/**', 'out/**', '.next/**', 'target/**',
+                '.git/**',
+                '*.png', '*.jpg', '*.jpeg', '*.gif', '*.ico', '*.svg', '*.bmp', '*.webp',
+                '*.woff', '*.woff2', '*.ttf', '*.eot',
+                '*.mp3', '*.mp4', '*.wav', '*.avi', '*.mkv', '*.webm',
+                '*.zip', '*.tar', '*.gz', '*.rar', '*.7z',
+                '*.exe', '*.dll', '*.so', '*.dylib', '*.bin',
+                '*.min.js', '*.min.css', '*.map',
+                'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+                'soul/data/**', 'data/**',
+            ],
+        },
+        search: {
+            bm25: { k1: 1.2, b: 0.75 },
+            topK: 10,
         },
-        search: {},
         assembly: {
             defaultBudget: 30000,       // Token budget for context assembly
+            layers: { fixed: 0.10, shortTerm: 0.30, associative: 0.40, spare: 0.20 },
+            dependencyDepth: 2,
         },
         backup: {},
         embedding: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "n2-soul",
-    "version": "7.0.0",
+    "version": "7.0.1",
     "description": "Multi-agent session orchestrator with KV-Cache, Ark safety, and Arachne code context for MCP",
     "main": "index.js",
     "scripts": {