opentology 0.2.3 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # OpenTology
 
-> CLI-managed RDF/SPARQL infrastructure with RDFS reasoning, SHACL validation, and interactive graph visualization -- Supabase for knowledge graphs
+> Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph
 
 [English](#english) | [한국어](#한국어)
 
@@ -8,351 +8,270 @@
 
 ## English
 
-### Architecture
-
-```mermaid
-graph TB
-    subgraph CLI["opentology CLI"]
-        Init[init]
-        Push[push]
-        Query[query]
-        Validate[validate]
-        Infer[infer]
-        More[...]
-    end
-
-    subgraph MCP["MCP Server"]
-        Tools[23 Tools]
-        Resource["opentology://schema"]
-    end
-
-    subgraph Adapter["StoreAdapter"]
-        HTTP["HTTP Mode\nOxigraph Server"]
-        Embedded["Embedded Mode\nWASM In-Process"]
-    end
-
-    subgraph Pipeline["Processing Pipeline"]
-        SHACL["SHACL Validation"]
-        RDFS["RDFS Reasoning"]
-    end
-
-    CLI --> Adapter
-    MCP --> Adapter
-    CLI --> Pipeline
-    Pipeline --> Adapter
-```
+Most MCP servers give AI assistants tools. OpenTology gives them **understanding**.
 
-Existing ontology tools have terrible developer experience. OpenTology gives you managed RDF with a simple CLI -- initialize a project, write Turtle, validate with SHACL, push with automatic RDFS inference, query, and visualize your graph in an interactive web UI, all from your terminal. It ships an MCP server so AI assistants can manage your knowledge graph directly. It runs in embedded mode with zero Docker dependency, or connects to an Oxigraph server over HTTP.
+When you connect OpenTology to Claude Code (or any MCP client), it doesn't just expose SPARQL queries — it builds a persistent knowledge graph of your project: module dependencies, architectural decisions, resolved bugs, session history, and code-level symbols. Then it **automatically instructs** the AI to check impact before editing, search past decisions before choosing, and record what it learns.
 
-### System Requirements
+The result: an AI assistant that remembers across sessions, understands your codebase structure, and thinks before it acts.
 
-- **Node.js** >= 20.0.0
-- **oxigraph** uses WebAssembly (WASM) — platform-independent, runs everywhere Node.js runs. No C++ compiler, Python, or native build tools needed.
+### How It Works
 
-### Quick Demo
+```
+npm install -g opentology          # 1. Install
+opentology context init            # 2. Initialize (creates graph + hooks + CLAUDE.md instructions)
+opentology context scan            # 3. Scan codebase into the knowledge graph
+                                   # 4. Done — AI now uses the graph automatically
+```
 
-```bash
-# Zero-install embedded mode (no Docker!)
-opentology init --embedded my-project
-
-# Define ontology with class hierarchy
-cat > ontology.ttl << 'EOF'
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix ex: <http://example.org/> .
-ex:Person a rdfs:Class .
-ex:Doctor rdfs:subClassOf ex:Person .
-ex:Kim a ex:Doctor ; ex:name "Dr. Kim" .
-ex:Lee a ex:Person ; ex:name "Lee" .
-EOF
-
-# Push with automatic RDFS inference
-opentology push ontology.ttl
-# -> Pushed 6 triples
-# -> Inferred 1 additional triples
+After setup, every session follows this cycle:
 
-# Query: Doctor instances found as Person (inference!)
-opentology query 'SELECT ?name WHERE { ?p a ex:Person . ?p ex:name ?name }'
-# -> Kim, Lee  (Kim is a Doctor, but inferred as Person)
 ```
-
-### Push Pipeline
-
-```mermaid
-graph LR
-    A["Write .ttl"] --> B["validate"]
-    B --> C{"SHACL shapes?"}
-    C -->|Yes| D["SHACL Check"]
-    C -->|No| E["push"]
-    D -->|Pass| E
-    D -->|Fail| F["Error"]
-    E --> G["RDFS Inference"]
-    G --> H["query"]
+┌─────────── Session Start ───────────┐
+│ SessionStart hook                   │
+│   → context_sync (auto-recover      │
+│     missed sessions, rescan modules) │
+│                                     │
+│ "Edit src/lib/reasoner.ts"          │
+│   → context_impact (blast radius)   │
+│   → "5 dependents, impact: high"    │
+│   → Confirms with user, then edits  │
+│                                     │
+│ Encounters a bug                    │
+│   → query (search past issues)      │
+│   → Finds similar resolved issue    │
+│                                     │
+│ Makes architecture decision         │
+│   → push (records Decision)         │
+│                                     │
+│ Session End                         │
+│   → push (records Session summary)  │
+└─────────────────────────────────────┘
 ```
 
-### Why OpenTology?
+### What Makes This Different
 
-| | OpenTology | Raw Oxigraph | Neo4j |
-|---|---|---|---|
-| Setup | `npm install -g opentology` | Manual binary/Docker config | Server install + license |
-| Docker required | No (embedded mode) | Yes | Yes |
-| RDFS reasoning | Automatic on push | Manual SPARQL CONSTRUCT | Not native |
-| SHACL validation | Built-in | Manual tooling | N/A |
-| AI integration | MCP server with 23 tools | None | Plugin ecosystem |
-| Query language | SPARQL (auto-prefixed) | SPARQL (raw) | Cypher |
-| Data format | Turtle files | Turtle/N-Triples | Property graph |
-| Project scoping | Automatic named graphs | Manual | Database-level |
-
-### Features
+| | Typical MCP | OpenTology |
+|---|---|---|
+| Provides | Tools only | Tools + behavioral instructions + auto-sync hooks |
+| AI behavior | User must prompt correctly | AI proactively checks impact, searches context |
+| Memory | Resets every session | Persistent knowledge graph across sessions |
+| Codebase awareness | None | Module dependencies, symbols, call graphs |
+| Setup | Manual per-project config | One command (`context init`) |
 
-**Core**
+OpenTology doesn't just add capabilities — it **shapes how the AI works** on your project.
 
-- 18 CLI commands covering the full RDF lifecycle
-- Project-level configuration with `.opentology.json`
-- Named graph scoping -- queries are automatically scoped to your project
-- Two modes: HTTP (Oxigraph server) and embedded (WASM, zero Docker)
-- Prefix registry with auto-injection into SPARQL queries
+### The Knowledge Graph
 
-**Reasoning**
+Everything lives in RDF named graphs with the `otx:` ontology:
 
-- RDFS inference: subClassOf, subPropertyOf, domain, range
-- Query `Person` and get `Doctor` instances automatically
-- Auto-materialization on push, manual control with `infer`
+```
+context graph                        sessions graph
+├── otx:Module (source files)        └── otx:Session (work logs)
+│   └── otx:dependsOn                    ├── otx:body (what was done)
+├── otx:Class / otx:Interface            └── otx:nextTodo (what's next)
+│   └── otx:Method / otx:Function
+├── otx:Decision (architecture choices)
+├── otx:Issue (bugs, status tracking)
+└── otx:Knowledge (reusable patterns)
+```
 
-**Validation**
+Query anything with SPARQL:
 
-- Turtle syntax validation before every push
-- SHACL shape constraint validation
-- `shapes/` directory convention for organizing shape files
+```sparql
+# What depends on this module?
+SELECT ?dep WHERE { ?dep otx:dependsOn <urn:module:src/lib/reasoner> }
 
-**AI Integration**
+# What decisions were made about auth?
+SELECT ?title ?reason WHERE {
+  ?d a otx:Decision ; otx:title ?title ; otx:reason ?reason
+  FILTER(CONTAINS(LCASE(?title), "auth"))
+}
 
-- MCP server with 23 tools and 1 resource
-- `opentology://schema` resource auto-loads ontology overview
-- Works with Claude Code, Cursor, and any MCP-compatible client
+# What did we do last session?
+SELECT ?title ?body ?next WHERE {
+  ?s a otx:Session ; otx:title ?title ; otx:body ?body
+  OPTIONAL { ?s otx:nextTodo ?next }
+} ORDER BY DESC(?date) LIMIT 1
+```
 
-**Visualization**
+### Quick Start
 
-- Interactive graph visualization web UI (`opentology context graph`)
-- Explore classes, instances, and relationships visually with vis-network
-- SPARQL query editor, node filtering, search, and focus mode
+#### 1. Add to your MCP client
 
-### Two Modes
+```json
+{
+  "mcpServers": {
+    "opentology": {
+      "command": "npx",
+      "args": ["-y", "opentology", "mcp"]
+    }
+  }
+}
+```
 
-| | HTTP Mode | Embedded Mode |
-|---|---|---|
-| Backend | Oxigraph server (Docker or binary) | In-process WASM store |
-| Docker | Required | Not required |
-| Init | `opentology init my-project` | `opentology init --embedded my-project` |
-| Source of truth | Oxigraph server | Local `.ttl` files |
-| Best for | Production, shared access | Local dev, quick experiments |
-| Performance | Server-grade | Single-user |
+#### 2. Initialize project context
 
-### Installation
+Ask your AI assistant to run `context_init`, or from the CLI:
 
 ```bash
-npm install -g opentology
+opentology context init
 ```
 
-**Prerequisites:** Node.js 20+
+This creates:
+- `.opentology.json` — project config
+- Context and sessions named graphs
+- SessionStart hook for auto-sync
+- CLAUDE.md instructions (impact checks, graph queries, session recording)
 
-For HTTP mode, you also need Oxigraph running:
+#### 3. Scan your codebase
 
 ```bash
-docker run -p 7878:7878 ghcr.io/oxigraph/oxigraph \
-  serve --location /data --bind 0.0.0.0:7878
+opentology context scan
 ```
 
-For embedded mode, no additional setup is needed.
-
-### CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `opentology init [project-id]` | Initialize project (`--embedded` for Docker-free mode) |
-| `opentology validate <file>` | Validate Turtle syntax (`--shacl` for SHACL validation) |
-| `opentology push <file>` | Push triples with auto SHACL validation and RDFS inference (`--replace`, `--no-shacl`, `--no-infer`) |
-| `opentology query <sparql>` | Run SPARQL with auto prefix injection (`--format table\|json\|csv`, `--raw`) |
-| `opentology status` | Show asserted/inferred/total triple counts (file count in embedded mode) |
-| `opentology pull` | Export project graph as Turtle |
-| `opentology drop` | Drop the entire project graph (`--force` to skip confirmation) |
-| `opentology delete <file>` | Delete triples from a file or by pattern (`--where`) |
-| `opentology diff <file>` | Compare local Turtle file against the graph |
-| `opentology shapes` | List or show SHACL shapes |
-| `opentology infer` | Run RDFS materialization (`--clear` to remove inferred triples) |
-| `opentology graph` | List, create, or drop named graphs |
-| `opentology prefix` | List, add, or remove project prefixes |
-| `opentology context` | Project context management (`init`, `load`, `status`, `scan`, `impact`, `sync`, `graph`) |
-| `opentology viz` | Visualize ontology schema (`schema`) |
-| `opentology doctor` | Check project health (config, store, context, hooks, dependencies) |
-| `opentology mcp` | Start the MCP server |
-
-### MCP Integration
-
-Add to your MCP client configuration (`.mcp.json`):
+Builds the module dependency graph. For deeper analysis:
 
 ```json
-{
-  "mcpServers": {
-    "opentology": {
-      "command": "npx",
-      "args": ["opentology", "mcp"]
-    }
-  }
-}
+{ "depth": "symbol", "includeMethodCalls": true }
 ```
 
-**23 Tools:**
-
-| Tool | Description |
-|------|-------------|
-| `opentology_init` | Initialize a project |
-| `opentology_validate` | Validate Turtle content |
-| `opentology_push` | Validate and push triples |
-| `opentology_query` | Execute SPARQL queries |
-| `opentology_status` | Get project status |
-| `opentology_pull` | Export graph as Turtle |
-| `opentology_drop` | Drop project graph |
-| `opentology_delete` | Delete triples |
-| `opentology_diff` | Compare local vs graph |
-| `opentology_schema` | Introspect ontology schema |
-| `opentology_infer` | Run RDFS inference |
-| `opentology_graph_list` | List named graphs |
-| `opentology_graph_create` | Create a named graph |
-| `opentology_graph_drop` | Drop a named graph |
-| `opentology_visualize` | Generate schema visualization (Mermaid/DOT) |
-| `opentology_context_init` | Initialize project context graph |
-| `opentology_context_load` | Load project context |
-| `opentology_context_status` | Check context initialization status |
-| `opentology_context_scan` | Scan codebase (module or symbol-level) |
-| `opentology_context_impact` | Analyze file modification impact (dependents, dependencies, related context) |
-| `opentology_context_sync` | Auto-sync: recover missed sessions from git, rescan module graph |
-| `opentology_context_graph` | Start interactive graph visualization web UI |
-| `opentology_doctor` | Check project health (config, store, hooks, dependencies) |
-
-**1 Resource:**
-
-| Resource | Description |
-|----------|-------------|
-| `opentology://schema` | Auto-loaded ontology overview (classes, properties, instances) |
-
-### RDFS Reasoning
-
-OpenTology automatically materializes RDFS inferences when you push data. If your ontology defines a class hierarchy, queries against a parent class return instances of all subclasses.
-
-```mermaid
-graph TD
-    Kim["ex:Kim"] -->|a| Doctor["ex:Doctor"]
-    Doctor -->|rdfs:subClassOf| MedProf["ex:MedicalProfessional"]
-    MedProf -->|rdfs:subClassOf| Person["ex:Person"]
-    Kim -.->|inferred: a| MedProf
-    Kim -.->|inferred: a| Person
-
-    style Kim fill:#4CAF50,color:white
-    style Doctor fill:#2196F3,color:white
-    style MedProf fill:#2196F3,color:white
-    style Person fill:#2196F3,color:white
-```
+#### 4. Work normally
 
-Supported inference rules:
+The AI now automatically:
+- Checks `context_impact` before editing files
+- Searches decisions/issues/knowledge when relevant
+- Records session summaries at the end
 
-- **rdfs:subClassOf** -- instances of subclass are instances of superclass
-- **rdfs:subPropertyOf** -- triples with subproperty imply triples with superproperty
-- **rdfs:domain** -- using a property implies the subject is of the domain class
-- **rdfs:range** -- using a property implies the object is of the range class
+### Codebase Scanning
 
-Use `opentology infer` to manually trigger materialization, or `opentology infer --clear` to remove inferred triples.
+| Depth | What it extracts | Use case |
+|-------|-----------------|----------|
+| `module` (default) | File-level import graph | Impact analysis, dependency tracking |
+| `symbol` | Classes, interfaces, functions, methods, call graphs | Deep code understanding |
 
-### SHACL Validation
+**Supported languages for symbol-level scan:**
 
-Place shape files in the `shapes/` directory. They are automatically validated on push.
+| Language | Engine |
+|----------|--------|
+| TypeScript/JavaScript | ts-morph |
+| Python | Tree-sitter |
+| Go | Tree-sitter |
+| Rust | Tree-sitter |
+| Java | Tree-sitter |
+| Swift | Tree-sitter |
 
-```turtle
-# shapes/person-shape.ttl
-@prefix sh: <http://www.w3.org/ns/shacl#> .
-@prefix ex: <http://example.org/> .
+Optional dependencies for symbol scan:
 
-ex:PersonShape a sh:NodeShape ;
-  sh:targetClass ex:Person ;
-  sh:property [
-    sh:path ex:name ;
-    sh:minCount 1 ;
-    sh:datatype xsd:string ;
-  ] .
+```bash
+npm install ts-morph                          # TypeScript/JavaScript
+npm install web-tree-sitter tree-sitter-wasms # Python, Go, Rust, Java, Swift
 ```
 
-```bash
-# Validate explicitly
-opentology validate --shacl data.ttl
+### RDF Infrastructure
 
-# Push auto-validates (skip with --no-shacl)
-opentology push data.ttl
+Under the hood, OpenTology is a full RDF/SPARQL toolkit:
 
-# List available shapes
-opentology shapes
-```
+- **RDFS reasoning** — push data, get automatic inference (subClassOf, domain, range)
+- **SHACL validation** — shape constraints checked on every push
+- **Two storage modes** — embedded (WASM, zero Docker) or HTTP (Oxigraph server)
+- **Interactive visualization** — web UI for exploring the graph (`opentology context graph`)
+- **Named graph scoping** — queries auto-scope to your project
 
-### Deep Scan (Symbol-Level Analysis)
+```bash
+# Push RDF data with auto-inference
+opentology push ontology.ttl
 
-The `opentology_context_scan` MCP tool supports symbol-level deep scanning that extracts classes, interfaces, functions, and method call relationships from source code, then pushes them as OTX triples to the context graph.
+# Query with auto-prefixed SPARQL
+opentology query 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'
 
-**Supported Languages:**
+# Visualize schema
+opentology viz schema
 
-| Language | Engine | Symbols Extracted |
-|----------|--------|-------------------|
-| TypeScript/JavaScript | ts-morph | class, interface, function, method calls |
-| Python | Tree-sitter | class, ABC/Protocol, function, method calls |
-| Go | Tree-sitter | struct, interface, func, method calls |
-| Rust | Tree-sitter | struct, trait, impl, fn, method calls |
-| Java | Tree-sitter | class, interface, method, method calls |
-| Swift | Tree-sitter | class, struct, protocol, func, method calls |
+# Health check
+opentology doctor
+```
 
-**Optional Dependencies:**
+### CLI Commands
 
-```bash
-# For TypeScript/JavaScript deep scan
-npm install ts-morph
+| Command | Description |
+|---------|-------------|
+| `context init` | Initialize project context (graphs + hooks + CLAUDE.md) |
+| `context scan` | Scan codebase into knowledge graph |
+| `context load` | Load recent sessions, open issues, decisions |
+| `context impact` | Analyze blast radius of a file change |
+| `context sync` | Auto-recover sessions from git, rescan modules |
+| `context graph` | Start interactive visualization web UI |
+| `init` | Initialize RDF project |
+| `push` | Push triples with SHACL validation + RDFS inference |
+| `query` | Execute SPARQL queries |
+| `validate` | Validate Turtle syntax and SHACL shapes |
+| `pull` | Export graph as Turtle |
+| `diff` | Compare local file vs graph |
+| `delete` | Delete triples by file or pattern |
+| `drop` | Drop entire graph |
+| `infer` | Run/clear RDFS materialization |
+| `graph` | Manage named graphs |
+| `status` | Show triple counts |
+| `doctor` | Diagnose project health |
+| `mcp` | Start MCP server |
+
+### MCP Tools (23)
 
-# For Python/Go/Rust/Java/Swift deep scan
-npm install web-tree-sitter tree-sitter-wasms
-```
+| Tool | Description |
+|------|-------------|
+| `context_init` | Initialize project context graph |
+| `context_load` | Load project context (sessions, issues, decisions) |
+| `context_scan` | Scan codebase (module or symbol-level) |
+| `context_impact` | Analyze file modification impact |
+| `context_sync` | Auto-sync from git history |
+| `context_status` | Check context initialization status |
+| `context_graph` | Start interactive graph visualization |
+| `init` | Initialize RDF project |
+| `push` | Validate and push triples |
+| `query` | Execute SPARQL queries |
+| `validate` | Validate Turtle content |
+| `pull` | Export graph as Turtle |
+| `drop` | Drop project graph |
+| `delete` | Delete triples |
+| `diff` | Compare local vs graph |
+| `schema` | Introspect ontology schema |
+| `infer` | Run RDFS inference |
+| `graph_list` | List named graphs |
+| `graph_create` | Create named graph |
+| `graph_drop` | Drop named graph |
+| `visualize` | Generate schema diagram (Mermaid/DOT) |
+| `status` | Get project status |
+| `doctor` | Check project health |
 
-**Usage (MCP):**
+### System Requirements
 
-```json
-{
-  "depth": "symbol",
-  "includeMethodCalls": true,
-  "languages": ["typescript", "python"]
-}
-```
+- **Node.js** >= 20.0.0
+- **oxigraph** uses WebAssembly — runs everywhere Node.js runs, no native build tools needed
 
 ### Tech Stack
 
-- TypeScript, commander.js, n3.js
-- Oxigraph WASM (embedded mode) / Oxigraph server (HTTP mode)
+- TypeScript, Oxigraph WASM, N3.js, commander.js
 - @modelcontextprotocol/sdk for MCP server
 - shacl-engine for SHACL validation
-- picocolors for terminal output
 - ts-morph (optional) for TypeScript symbol analysis
-- web-tree-sitter + tree-sitter-wasms (optional) for multi-language symbol analysis
+- web-tree-sitter + tree-sitter-wasms (optional) for multi-language analysis
 
 ### Roadmap
 
-- [x] CLI with 18 commands
-- [x] MCP server with 23 tools and 1 resource
-- [x] Schema introspection (MCP resource + tool)
-- [x] Complete CRUD (push --replace, drop, delete)
-- [x] SHACL validation (shape constraints on push)
-- [x] DX polish (diff, colors, better errors)
-- [x] Multi-graph support
-- [x] Prefix management
-- [x] Embedded mode (no Docker required)
-- [x] RDFS reasoning (auto-materialization on push)
-- [x] Multi-language deep scan (TypeScript, Python, Go, Rust, Java, Swift)
+- [x] Full RDF lifecycle CLI (18 commands)
+- [x] MCP server (23 tools + 1 resource)
+- [x] RDFS reasoning with auto-materialization
+- [x] SHACL validation
+- [x] Embedded mode (zero Docker)
+- [x] Project context graph (decisions, issues, sessions)
+- [x] Codebase scanning (module + symbol level, 6 languages)
+- [x] Impact analysis with dependency tracking
+- [x] Auto-sync from git history
+- [x] AI behavioral instructions via CLAUDE.md injection
+- [x] Interactive graph visualization web UI
 - [ ] OWL reasoning (owl:sameAs, owl:inverseOf)
 - [ ] Remote ontology import
-- [ ] Version control for ontology snapshots
-- [x] Interactive graph visualization web UI
+- [ ] Ontology snapshot versioning
 
 ### Contributing
 
@@ -369,351 +288,270 @@ MIT
 
 ## 한국어
 
-### 아키텍처
-
-```mermaid
-graph TB
-    subgraph CLI["opentology CLI"]
-        Init[init]
-        Push[push]
-        Query[query]
-        Validate[validate]
-        Infer[infer]
-        More[...]
-    end
-
-    subgraph MCP["MCP Server"]
-        Tools[23 Tools]
-        Resource["opentology://schema"]
-    end
-
-    subgraph Adapter["StoreAdapter"]
-        HTTP["HTTP Mode\nOxigraph Server"]
-        Embedded["Embedded Mode\nWASM In-Process"]
-    end
-
-    subgraph Pipeline["Processing Pipeline"]
-        SHACL["SHACL Validation"]
-        RDFS["RDFS Reasoning"]
-    end
-
-    CLI --> Adapter
-    MCP --> Adapter
-    CLI --> Pipeline
-    Pipeline --> Adapter
-```
-
-온톨로지 도구들은 개발자 경험이 열악합니다. OpenTology는 터미널에서 RDF의 전체 생애주기를 관리합니다. 프로젝트 초기화, Turtle 작성, SHACL 검증, RDFS 추론이 포함된 푸시, SPARQL 쿼리, 인터랙티브 그래프 시각화까지 CLI 하나로 처리합니다. MCP 서버를 내장하고 있어 AI 어시스턴트가 지식 그래프를 직접 다룰 수 있고, Docker 없이 임베디드 모드로 바로 시작할 수 있습니다.
-
-### 시스템 요구사항
+대부분의 MCP 서버는 AI에게 도구를 줍니다. OpenTology는 AI에게 **이해**를 줍니다.
 
-- **Node.js** >= 20.0.0
-- **oxigraph**는 WebAssembly(WASM)를 사용하므로 플랫폼 독립적입니다. Node.js가 실행되는 모든 환경에서 동작하며, C++ 컴파일러, Python, 또는 네이티브 빌드 도구가 필요하지 않습니다.
+OpenTology를 Claude Code(또는 MCP 호환 클라이언트)에 연결하면, 단순히 SPARQL 쿼리를 노출하는 것이 아니라 프로젝트의 영속적인 지식 그래프를 구축합니다: 모듈 의존성, 아키텍처 의사결정, 해결된 버그, 세션 이력, 코드 수준의 심볼까지. 그리고 AI가 **자동으로** 편집 전에 영향도를 확인하고, 의사결정 전에 과거 기록을 검색하고, 배운 것을 기록하도록 **지침을 주입**합니다.
 
-### 빠른 시작
+결과: 세션을 넘어 기억하고, 코드베이스 구조를 이해하며, 행동 전에 생각하는 AI 어시스턴트.
 
-```bash
-# Docker 없이 바로 시작 (임베디드 모드)
-opentology init --embedded my-project
-
-# 클래스 계층 구조가 포함된 온톨로지 작성
-cat > ontology.ttl << 'EOF'
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix ex: <http://example.org/> .
-ex:Person a rdfs:Class .
-ex:Doctor rdfs:subClassOf ex:Person .
-ex:Kim a ex:Doctor ; ex:name "Dr. Kim" .
-ex:Lee a ex:Person ; ex:name "Lee" .
-EOF
-
-# RDFS 추론 포함 자동 푸시
-opentology push ontology.ttl
-# -> Pushed 6 triples
-# -> Inferred 1 additional triples
+### 작동 방식
 
-# Doctor를 Person으로 자동 추론하여 결과에 포함
-opentology query 'SELECT ?name WHERE { ?p a ex:Person . ?p ex:name ?name }'
-# -> Kim, Lee  (Kim은 Doctor이지만 Person으로 추론됨)
 ```
-
-### 푸시 파이프라인
-
-```mermaid
-graph LR
-    A["Write .ttl"] --> B["validate"]
-    B --> C{"SHACL shapes?"}
-    C -->|Yes| D["SHACL Check"]
-    C -->|No| E["push"]
-    D -->|Pass| E
-    D -->|Fail| F["Error"]
-    E --> G["RDFS Inference"]
-    G --> H["query"]
+npm install -g opentology          # 1. 설치
+opentology context init            # 2. 초기화 (그래프 + 훅 + CLAUDE.md 지침 생성)
+opentology context scan            # 3. 코드베이스를 지식 그래프로 스캔
+                                   # 4. 끝 — AI가 자동으로 그래프를 활용
 ```
 
-### OpenTology를 쓰는 이유
-
-| | OpenTology | Oxigraph 직접 사용 | Neo4j |
-|---|---|---|---|
-| 설치 | `npm install -g opentology` | 바이너리/Docker 직접 구성 | 서버 설치 + 라이선스 |
-| Docker 필수 | 아니오 (임베디드 모드) | 예 | 예 |
-| RDFS 추론 | 푸시 시 자동 | SPARQL CONSTRUCT 수동 작성 | 네이티브 미지원 |
-| SHACL 검증 | 내장 | 별도 도구 필요 | 해당 없음 |
-| AI 연동 | MCP 서버 23개 도구 | 없음 | 플러그인 생태계 |
-| 쿼리 언어 | SPARQL (접두사 자동 삽입) | SPARQL (수동) | Cypher |
-| 데이터 형식 | Turtle 파일 | Turtle/N-Triples | 속성 그래프 |
-| 프로젝트 구분 | Named Graph 자동 | 수동 관리 | 데이터베이스 단위 |
-
-### 주요 기능
-
-**핵심**
-
-- RDF 전체 생애주기를 다루는 18개 CLI 명령어
-- `.opentology.json` 기반 프로젝트 설정
-- Named Graph 자동 스코핑 -- 쿼리가 프로젝트 그래프에 자동 한정
-- HTTP 모드(Oxigraph 서버)와 임베디드 모드(WASM, Docker 불필요) 지원
-- 프로젝트 수준 접두사 레지스트리, SPARQL 쿼리에 자동 삽입
-
-**추론**
-
-- RDFS 추론: subClassOf, subPropertyOf, domain, range
-- `Person`을 쿼리하면 `Doctor` 인스턴스도 자동 포함
-- 푸시 시 자동 물질화, `infer` 명령어로 수동 제어
-
-**검증**
-
-- 푸시 전 Turtle 문법 자동 검증
-- SHACL 형상 제약 조건 검증
-- `shapes/` 디렉토리 규칙으로 형상 파일 관리
+설정 후 매 세션은 이 사이클을 따릅니다:
 
-**AI 연동**
-
-- 23개 도구와 1개 리소스를 제공하는 MCP 서버
-- `opentology://schema` 리소스로 온톨로지 개요 자동 로드
-- Claude Code, Cursor 등 MCP 호환 클라이언트와 연동
+```
+┌─────────── 세션 시작 ───────────────┐
+│ SessionStart 훅                     │
+│   → context_sync (놓친 세션 복구,    │
+│     모듈 그래프 갱신)                │
+│                                     │
+│ "src/lib/reasoner.ts 수정해줘"      │
+│   → context_impact (폭발 반경 확인) │
+│   → "5개 의존 모듈, impact: high"   │
+│   → 유저 확인 후 수정               │
+│                                     │
+│ 버그 발생                           │
+│   → query (과거 이슈 검색)          │
+│   → 유사한 해결 이슈 발견           │
+│                                     │
+│ 아키텍처 의사결정                    │
+│   → push (Decision 기록)            │
+│                                     │
+│ 세션 종료                           │
+│   → push (Session 요약 기록)        │
+└─────────────────────────────────────┘
+```
 
-**시각화**
+### 무엇이 다른가
 
-- 인터랙티브 그래프 시각화 웹 UI (`opentology context graph`)
-- vis-network로 클래스, 인스턴스, 관계를 시각적으로 탐색
-- SPARQL 쿼리 편집기, 노드 필터링, 검색, 포커스 모드
+| | 일반 MCP | OpenTology |
+|---|---|---|
+| 제공하는 것 | 도구만 | 도구 + 행동 지침 + 자동 동기화 훅 |
+| AI 행동 | 유저가 정확히 프롬프트해야 함 | AI가 자발적으로 영향도 확인, 컨텍스트 검색 |
+| 메모리 | 매 세션 리셋 | 세션을 넘어 영속하는 지식 그래프 |
+| 코드베이스 인식 | 없음 | 모듈 의존성, 심볼, 호출 그래프 |
+| 설정 | 프로젝트마다 수동 설정 | 명령어 하나 (`context init`) |
 
-### 두 가지 모드
+OpenTology는 기능만 추가하는 것이 아니라, **AI가 프로젝트에서 일하는 방식 자체를 바꿉니다**.
 
-| | HTTP 모드 | 임베디드 모드 |
-|---|---|---|
-| 백엔드 | Oxigraph 서버 (Docker 또는 바이너리) | 인프로세스 WASM 스토어 |
-| Docker | 필요 | 불필요 |
-| 초기화 | `opentology init my-project` | `opentology init --embedded my-project` |
-| 원본 데이터 | Oxigraph 서버 | 로컬 `.ttl` 파일 |
-| 적합한 용도 | 프로덕션, 공유 환경 | 로컬 개발, 빠른 실험 |
-| 성능 | 서버급 | 단일 사용자 |
+### 지식 그래프 구조
 
-### 설치
+모든 데이터는 `otx:` 온톨로지를 사용하는 RDF named graph에 저장됩니다:
 
-```bash
-npm install -g opentology
+```
+context graph                        sessions graph
+├── otx:Module (소스 파일)             └── otx:Session (작업 로그)
+│   └── otx:dependsOn                    ├── otx:body (수행한 작업)
+├── otx:Class / otx:Interface            └── otx:nextTodo (다음 할 일)
+│   └── otx:Method / otx:Function
+├── otx:Decision (아키텍처 의사결정)
+├── otx:Issue (버그, 상태 추적)
+└── otx:Knowledge (재사용 가능한 패턴)
 ```
 
-**필수 조건:** Node.js 20+
+SPARQL로 무엇이든 쿼리 가능:
 
-HTTP 모드를 사용하려면 Oxigraph 서버가 필요합니다:
+```sparql
+# 이 모듈에 의존하는 것은?
+SELECT ?dep WHERE { ?dep otx:dependsOn <urn:module:src/lib/reasoner> }
 
-```bash
-docker run -p 7878:7878 ghcr.io/oxigraph/oxigraph \
-  serve --location /data --bind 0.0.0.0:7878
-```
+# 인증 관련 의사결정은?
+SELECT ?title ?reason WHERE {
+  ?d a otx:Decision ; otx:title ?title ; otx:reason ?reason
+  FILTER(CONTAINS(LCASE(?title), "auth"))
+}
 
-임베디드 모드는 추가 설치가 필요 없습니다.
+# 지난 세션에서 뭘 했지?
+SELECT ?title ?body ?next WHERE {
+  ?s a otx:Session ; otx:title ?title ; otx:body ?body
+  OPTIONAL { ?s otx:nextTodo ?next }
+} ORDER BY DESC(?date) LIMIT 1
+```
 
-### CLI 명령어
+### 빠른 시작
 
-| 명령어 | 설명 |
-|--------|------|
-| `opentology init [project-id]` | 프로젝트 초기화 (`--embedded`로 Docker 불필요 모드) |
-| `opentology validate <file>` | Turtle 문법 검증 (`--shacl`로 SHACL 검증) |
-| `opentology push <file>` | SHACL 자동 검증 + RDFS 추론 포함 푸시 (`--replace`, `--no-shacl`, `--no-infer`) |
-| `opentology query <sparql>` | 접두사 자동 삽입 SPARQL 실행 (`--format table\|json\|csv`, `--raw`) |
-| `opentology status` | asserted/inferred/total 트리플 수 표시 (임베디드 모드에서 파일 수 포함) |
-| `opentology pull` | 프로젝트 그래프를 Turtle로 내보내기 |
-| `opentology drop` | 프로젝트 그래프 전체 삭제 (`--force`로 확인 생략) |
-| `opentology delete <file>` | 파일 또는 패턴(`--where`)으로 트리플 삭제 |
-| `opentology diff <file>` | 로컬 Turtle 파일과 그래프 비교 |
-| `opentology shapes` | SHACL 형상 목록 조회/상세 보기 |
-| `opentology infer` | RDFS 물질화 실행 (`--clear`로 추론 트리플 제거) |
-| `opentology graph` | Named Graph 목록/생성/삭제 |
-| `opentology prefix` | 프로젝트 접두사 목록/추가/제거 |
-| `opentology context` | 프로젝트 컨텍스트 관리 (`init`, `load`, `status`, `scan`, `impact`, `sync`, `graph`) |
-| `opentology viz` | 온톨로지 스키마 시각화 (`schema`) |
-| `opentology doctor` | 프로젝트 건강 진단 (설정, 스토어, 컨텍스트, 훅, 의존성) |
-| `opentology mcp` | MCP 서버 시작 |
-
-### MCP 연동
-
-MCP 클라이언트 설정 파일(`.mcp.json`)에 추가:
+#### 1. MCP 클라이언트에 추가
 
 ```json
 {
   "mcpServers": {
     "opentology": {
       "command": "npx",
-      "args": ["opentology", "mcp"]
+      "args": ["-y", "opentology", "mcp"]
     }
   }
 }
 ```
 
-**23개 도구:**
+#### 2. 프로젝트 컨텍스트 초기화
 
-| 도구 | 설명 |
-|------|------|
-| `opentology_init` | 프로젝트 초기화 |
-| `opentology_validate` | Turtle 내용 검증 |
-| `opentology_push` | 트리플 검증 및 푸시 |
-| `opentology_query` | SPARQL 쿼리 실행 |
-| `opentology_status` | 프로젝트 상태 조회 |
-| `opentology_pull` | 그래프를 Turtle로 내보내기 |
-| `opentology_drop` | 프로젝트 그래프 삭제 |
-| `opentology_delete` | 트리플 삭제 |
-| `opentology_diff` | 로컬 파일과 그래프 비교 |
-| `opentology_schema` | 온톨로지 스키마 조회 |
-| `opentology_infer` | RDFS 추론 실행 |
-| `opentology_graph_list` | Named Graph 목록 조회 |
-| `opentology_graph_create` | Named Graph 생성 |
-| `opentology_graph_drop` | Named Graph 삭제 |
-| `opentology_visualize` | 스키마 시각화 생성 (Mermaid/DOT) |
-| `opentology_context_init` | 프로젝트 컨텍스트 그래프 초기화 |
-| `opentology_context_load` | 프로젝트 컨텍스트 로드 |
-| `opentology_context_status` | 컨텍스트 초기화 상태 확인 |
-| `opentology_context_scan` | 코드베이스 스캔 (모듈/심볼 수준) |
-| `opentology_context_impact` | 파일 수정 영향 분석 (의존 모듈, 관련 컨텍스트) |
-| `opentology_context_sync` | 자동 동기화: git에서 누락 세션 복구, 모듈 그래프 재스캔 |
-| `opentology_context_graph` | 인터랙티브 그래프 시각화 웹 UI 시작 |
-| `opentology_doctor` | 프로젝트 건강 진단 (설정, 스토어, 훅, 의존성) |
-
-**1개 리소스:**
-
-| 리소스 | 설명 |
-|--------|------|
-| `opentology://schema` | 온톨로지 개요 자동 로드 (클래스, 속성, 인스턴스) |
+AI 어시스턴트에게 `context_init` 실행을 요청하거나, CLI에서:
 
-### RDFS 추론
+```bash
+opentology context init
+```
 
-데이터를 푸시하면 RDFS 추론이 자동으로 물질화됩니다. 온톨로지에 클래스 계층이 정의되어 있으면, 상위 클래스를 쿼리할 때 하위 클래스의 인스턴스도 함께 반환됩니다.
+생성되는 것:
+- `.opentology.json` — 프로젝트 설정
+- context / sessions named graph
+- SessionStart 훅 (자동 동기화)
+- CLAUDE.md 지침 (영향도 확인, 그래프 쿼리, 세션 기록)
 
-```mermaid
-graph TD
-    Kim["ex:Kim"] -->|a| Doctor["ex:Doctor"]
-    Doctor -->|rdfs:subClassOf| MedProf["ex:MedicalProfessional"]
-    MedProf -->|rdfs:subClassOf| Person["ex:Person"]
-    Kim -.->|inferred: a| MedProf
-    Kim -.->|inferred: a| Person
+#### 3. 코드베이스 스캔
 
-    style Kim fill:#4CAF50,color:white
-    style Doctor fill:#2196F3,color:white
-    style MedProf fill:#2196F3,color:white
-    style Person fill:#2196F3,color:white
+```bash
+opentology context scan
 ```
 
-지원하는 추론 규칙:
+모듈 의존성 그래프를 구축합니다. 심볼 수준 분석:
 
-- **rdfs:subClassOf** -- 하위 클래스의 인스턴스는 상위 클래스의 인스턴스
-- **rdfs:subPropertyOf** -- 하위 속성의 트리플은 상위 속성의 트리플을 함의
-- **rdfs:domain** -- 속성 사용 시 주어가 도메인 클래스의 인스턴스임을 함의
-- **rdfs:range** -- 속성 사용 시 목적어가 범위 클래스의 인스턴스임을 함의
+```json
+{ "depth": "symbol", "includeMethodCalls": true }
+```
 
-`opentology infer`로 수동 물질화, `opentology infer --clear`로 추론 트리플 제거가 가능합니다.
+#### 4. 평소처럼 작업
 
-### SHACL 검증
+AI가 자동으로:
+- 파일 수정 전 `context_impact`로 영향도 확인
+- 관련 의사결정/이슈/지식 검색
+- 세션 종료 시 작업 요약 기록
 
-`shapes/` 디렉토리에 형상 파일을 배치하면 푸시 시 자동으로 검증됩니다.
+### 코드베이스 스캔
 
-```turtle
-# shapes/person-shape.ttl
-@prefix sh: <http://www.w3.org/ns/shacl#> .
-@prefix ex: <http://example.org/> .
+| 깊이 | 추출 내용 | 용도 |
+|------|----------|------|
+| `module` (기본) | 파일 수준 import 그래프 | 영향도 분석, 의존성 추적 |
+| `symbol` | 클래스, 인터페이스, 함수, 메서드, 호출 그래프 | 심층 코드 이해 |
 
-ex:PersonShape a sh:NodeShape ;
-  sh:targetClass ex:Person ;
-  sh:property [
-    sh:path ex:name ;
-    sh:minCount 1 ;
-    sh:datatype xsd:string ;
-  ] .
-```
+**심볼 스캔 지원 언어:**
 
-```bash
-# 명시적 검증
-opentology validate --shacl data.ttl
+| 언어 | 엔진 |
+|------|------|
+| TypeScript/JavaScript | ts-morph |
+| Python | Tree-sitter |
+| Go | Tree-sitter |
+| Rust | Tree-sitter |
+| Java | Tree-sitter |
+| Swift | Tree-sitter |
 
-# 푸시 시 자동 검증 (--no-shacl로 생략 가능)
-opentology push data.ttl
+심볼 스캔 선택적 의존성:
 
-# 등록된 형상 목록 조회
-opentology shapes
+```bash
+npm install ts-morph                          # TypeScript/JavaScript
+npm install web-tree-sitter tree-sitter-wasms # Python, Go, Rust, Java, Swift
 ```
 
-### 딥스캔 (심볼 수준 분석)
+### RDF 인프라
 
-`opentology_context_scan` MCP 도구는 소스 코드에서 클래스, 인터페이스, 함수, 메서드 호출 관계를 추출하여 OTX 트리플로 컨텍스트 그래프에 푸시하는 심볼 수준 딥스캔을 지원합니다.
+내부적으로 OpenTology는 완전한 RDF/SPARQL 툴킷입니다:
 
-**지원 언어:**
+- **RDFS 추론** — 데이터 푸시 시 자동 추론 (subClassOf, domain, range)
+- **SHACL 검증** — 푸시마다 형상 제약 자동 검증
+- **두 가지 스토리지 모드** — 임베디드 (WASM, Docker 불필요) 또는 HTTP (Oxigraph 서버)
+- **인터랙티브 시각화** — 그래프 탐색 웹 UI (`opentology context graph`)
+- **Named graph 스코핑** — 쿼리가 프로젝트에 자동 한정
 
-| 언어 | 엔진 | 추출 심볼 |
-|------|------|-----------|
-| TypeScript/JavaScript | ts-morph | class, interface, function, method calls |
-| Python | Tree-sitter | class, ABC/Protocol, function, method calls |
-| Go | Tree-sitter | struct, interface, func, method calls |
-| Rust | Tree-sitter | struct, trait, impl, fn, method calls |
-| Java | Tree-sitter | class, interface, method, method calls |
-| Swift | Tree-sitter | class, struct, protocol, func, method calls |
+```bash
+# RDFS 추론 포함 데이터 푸시
+opentology push ontology.ttl
 
-**선택적 의존성:**
+# 접두사 자동 삽입 SPARQL 쿼리
+opentology query 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'
 
-```bash
-# TypeScript/JavaScript 딥스캔
-npm install ts-morph
+# 스키마 시각화
+opentology viz schema
 
-# Python/Go/Rust/Java/Swift 딥스캔
-npm install web-tree-sitter tree-sitter-wasms
+# 건강 진단
+opentology doctor
 ```
 
-**사용법 (MCP):**
+### CLI 명령어
 
-```json
-{
-  "depth": "symbol",
-  "includeMethodCalls": true,
-  "languages": ["typescript", "python"]
-}
-```
+| 명령어 | 설명 |
+|--------|------|
+| `context init` | 프로젝트 컨텍스트 초기화 (그래프 + 훅 + CLAUDE.md) |
+| `context scan` | 코드베이스를 지식 그래프로 스캔 |
+| `context load` | 최근 세션, 미해결 이슈, 의사결정 로드 |
+| `context impact` | 파일 변경의 폭발 반경 분석 |
+| `context sync` | git 이력에서 세션 복구, 모듈 재스캔 |
+| `context graph` | 인터랙티브 시각화 웹 UI 시작 |
+| `init` | RDF 프로젝트 초기화 |
+| `push` | SHACL 검증 + RDFS 추론 포함 트리플 푸시 |
+| `query` | SPARQL 쿼리 실행 |
+| `validate` | Turtle 문법 및 SHACL 검증 |
+| `pull` | 그래프를 Turtle로 내보내기 |
+| `diff` | 로컬 파일과 그래프 비교 |
+| `delete` | 파일/패턴으로 트리플 삭제 |
+| `drop` | 그래프 전체 삭제 |
+| `infer` | RDFS 물질화 실행/정리 |
+| `graph` | Named graph 관리 |
+| `status` | 트리플 수 표시 |
+| `doctor` | 프로젝트 건강 진단 |
+| `mcp` | MCP 서버 시작 |
+
+### MCP 도구 (23개)
+
+| 도구 | 설명 |
+|------|------|
+| `context_init` | 프로젝트 컨텍스트 그래프 초기화 |
+| `context_load` | 프로젝트 컨텍스트 로드 (세션, 이슈, 의사결정) |
+| `context_scan` | 코드베이스 스캔 (모듈/심볼 수준) |
+| `context_impact` | 파일 수정 영향도 분석 |
+| `context_sync` | git 이력에서 자동 동기화 |
+| `context_status` | 컨텍스트 초기화 상태 확인 |
+| `context_graph` | 인터랙티브 그래프 시각화 시작 |
+| `init` | RDF 프로젝트 초기화 |
+| `push` | 트리플 검증 및 푸시 |
+| `query` | SPARQL 쿼리 실행 |
+| `validate` | Turtle 내용 검증 |
+| `pull` | 그래프를 Turtle로 내보내기 |
+| `drop` | 프로젝트 그래프 삭제 |
+| `delete` | 트리플 삭제 |
+| `diff` | 로컬 파일과 그래프 비교 |
+| `schema` | 온톨로지 스키마 조회 |
+| `infer` | RDFS 추론 실행 |
+| `graph_list` | Named graph 목록 |
+| `graph_create` | Named graph 생성 |
+| `graph_drop` | Named graph 삭제 |
+| `visualize` | 스키마 다이어그램 생성 (Mermaid/DOT) |
+| `status` | 프로젝트 상태 조회 |
+| `doctor` | 프로젝트 건강 진단 |
+
+### 시스템 요구사항
+
+- **Node.js** >= 20.0.0
+- **oxigraph**는 WebAssembly를 사용하므로 Node.js가 실행되는 모든 환경에서 동작합니다
 
 ### 기술 스택
 
-- TypeScript, commander.js, n3.js
-- Oxigraph WASM (임베디드 모드) / Oxigraph 서버 (HTTP 모드)
+- TypeScript, Oxigraph WASM, N3.js, commander.js
 - @modelcontextprotocol/sdk (MCP 서버)
 - shacl-engine (SHACL 검증)
-- picocolors (터미널 출력)
 - ts-morph (선택) TypeScript 심볼 분석
-- web-tree-sitter + tree-sitter-wasms (선택) 다중 언어 심볼 분석
+- web-tree-sitter + tree-sitter-wasms (선택) 다중 언어 분석
 
 ### 로드맵
 
-- [x] 18개 CLI 명령어
-- [x] 23개 도구와 1개 리소스를 갖춘 MCP 서버
-- [x] 스키마 조회 (MCP 리소스 + 도구)
-- [x] 완전한 CRUD (push --replace, drop, delete)
-- [x] SHACL 검증 (푸시 시 형상 제약 자동 검증)
-- [x] DX 개선 (diff, 컬러 출력, 에러 메시지)
-- [x] 멀티 그래프 지원
-- [x] 접두사 관리
+- [x] 전체 RDF 생애주기 CLI (18개 명령어)
+- [x] MCP 서버 (23개 도구 + 1개 리소스)
+- [x] RDFS 추론 (자동 물질화)
+- [x] SHACL 검증
 - [x] 임베디드 모드 (Docker 불필요)
-- [x] RDFS 추론 (푸시 시 자동 물질화)
-- [x] 다중 언어 딥스캔 (TypeScript, Python, Go, Rust, Java, Swift)
+- [x] 프로젝트 컨텍스트 그래프 (의사결정, 이슈, 세션)
+- [x] 코드베이스 스캔 (모듈 + 심볼 수준, 6개 언어)
+- [x] 의존성 추적 기반 영향도 분석
+- [x] git 이력에서 자동 동기화
+- [x] CLAUDE.md 주입을 통한 AI 행동 지침
+- [x] 인터랙티브 그래프 시각화 웹 UI
 - [ ] OWL 추론 (owl:sameAs, owl:inverseOf)
 - [ ] 원격 온톨로지 임포트
 - [ ] 온톨로지 스냅샷 버전 관리
-- [x] 인터랙티브 그래프 시각화 웹 UI
 
 ### 기여 방법