# v0.3 — Cognitive Layer Track Handover

> **Status (2026-05-17)**: Phase 0 (4 PR), Phase 1 (3 PR — PR-1/PR-2 +
> pipeline split), Phase 2 (3 PR — PR-5/PR-6/PR-8) **머지 완료**. §3
> 의 PR 표 참조. 본 트랙의 다음 코드 작업은 **Phase 2 PR-7 Planner**
> 또는 **Phase 3 PR-9 Episodic memory**. 자세한 session 결산은
> `v0.3.x-session-2026-05-17-closure.md`.
>
> **Active handover** (2026-05-14~). 사이클 8 (Knowledge Cascade) closure
> 직후 신설. v0.3 의 **두 번째 메인 트랙**.
>
> **Supersedes (in priority, not in audit trail)**: 사이클 7 (Plugin API)
> 가 본 트랙 closure 후로 슬립됨. `v0.3.0-platform-track.md` §3 의 사이클
> 7 항목은 v0.3.x 후반 또는 v0.4 로 재배치.

---

## 0. 한 줄 요약

JAMES 는 "search system" 이 아니라 "thinking system" 으로 진화한다.
기존 graph/ontology/security 코어는 그대로 유지하고, 위에 **cognitive
middleware** 를 얹어 retrieval → reflection → verification → synthesis
의 4 단계 파이프라인을 만든다. agent sprawl 없이 controlled.

---

## 1. 전략 frame (사용자 브리핑 2026-05-14)

### 1.1 강점은 보존, 약점만 채운다
현 시스템의 차별화는:
- Local-first
- Security-oriented (RBAC + ABAC + PolicyEngine + Memory Trust)
- Ontology-based graph memory (사이클 8 Knowledge Cascade 로 sources/cascade 완성)
- Auditability

**이 코어를 다시 짓지 않는다.** rebuild 는 가장 어려운 부분을 버리는
실수.

### 1.2 부족한 것
- Multi-step reasoning
- Planner / decomposer
- Reflection loop
- Verification layer
- Tool reasoning
- Working / episodic memory

현 동작:
```
question → retrieve() → answer()
```

목표 동작:
```
question
  → task decomposition
  → retrieval planning
  → multi-hop retrieval
  → hypothesis generation
  → reflection
  → verification
  → final synthesis
```

### 1.3 포지셔닝
JAMES 는 "another chatbot" 도 "another RAG wrapper" 도 아니다. 가장
방어 가능한 longterm 포지션:

> **Secure Cognitive Operating System** for organizational knowledge

다른 AI 시스템은 "instant intelligence" 를 최적화. JAMES 는 **"persistent
secure organizational cognition"** 를 최적화한다.

### 1.4 가장 강한 차별화 = security-aware reasoning
graph 관계로 보호된 정보 위에서 안전하게 추론할 수 있는 시스템은 드물다:
- prompt injection 감지
- privilege escalation reasoning
- 관계 기반 access reasoning
- contradiction detection
- data poisoning awareness
- forensic reasoning trails

`PolicyEngine` + `Memory Trust` + `sources cascade` 가 이미 기초.
cognitive middleware 가 이걸 적극 활용하면 차별화가 강해진다.

---

## 2. 4건의 사전 결정 (2026-05-14)

이번 트랙 진입 전에 사용자가 명시적으로 채택한 갈림길:

| # | 항목 | 결정 | 이유 |
|---|---|---|---|
| 1 | Plugin API (사이클 7) 위치 | **v0.3.x 또는 v0.4 로 슬립** | 외부 기여자 트리거 발생 전까지 ROI 낮음. cognitive middleware 가 사용자 가치 즉시 |
| 2 | CR-E (사이클 9) 통합 | **Verification engine 과 합쳐 진행** | 디자인이 같은 가족 (generator → critic → fact-checker) |
| 3 | Reranker 의존성 | **cross-encoder 모델 추가** (~50MB, local) | local-first 정합. 휴리스틱보다 품질 |
| 4 | ARCHITECTURE.md 갱신 시점 | **트랙 시작 전** | rule #4 정합. 새 trust zone 사전 합의 |

## 2.5 Hermes-style multi-agent OS 피드백 흡수 (2026-05-14 후속)

PR #275 의 초안 후, 사용자가 첨부한 Hermes 5-layer container 구조에
대해 추가 피드백. 해석 + 흡수 결과:

**Hermes 5-layer 핵심**:
```
LAYER 1  Company Brain   (vision/products, 모든 layer 가 상속)
LAYER 2  Orchestrator    (부서 선택)
LAYER 3  Department Brains (marketing/sales/ops/support)
LAYER 4  Specialized Agents (writer/critic/deploy/triage 등 ~12개)
LAYER 5  Docker isolation (1 container per agent)
```

**JAMES 정체성 유지 관점에서 4분류**:

### 🟢 흡수 (§5.7 에 반영, 본 PR)
- **Memory Scope Layering** (system / workspace / session) — §5.7.6 신설.
  Hermes 의 "context inheritance hierarchy" 가 JAMES 의 graph 와 정합
- **Roles vs workers 구분** — §5.7.3 보강. 5 agent role cap 은 concurrent
  reasoning agents 에만 적용; stateless worker function 은 무제한 허용
- **Trace replay invariant** — §5.7.2 보강. audit_bridge 만으로 결정
  rationale 완전 재구성 가능해야 (forensic reasoning 차별화)

### 🟡 보류 (§5.7.7 에 명시, v0.4 옵션)
- Container per agent / Docker isolation — RBAC/ABAC/PolicyEngine 이 이미
  더 정밀. Docker 는 v0.4 의 operator packaging 옵션 (`JAMES_WORKSPACE`
  env 위에서)
- Multi-workspace federation — v0.4 별 PR

### 🔴 거름 (적용 안 함, ARCH §5.7.5 + §5.7.6 에 명시)
- 도메인별 brain (intelligence / legal / cyber) 을 platform layer 로 박기 —
  CLAUDE.md rule #1 위반. 본 모델에서는 v1.0 이후 workspace-scoped plugin
- "one VPS = one AI company" 포지셔닝 — JAMES = cognitive infra, not
  company workflow engine
- Hermes 식 12 agent explosion — agent ≠ worker. JAMES 는 reasoning
  depth 우선, sprawl 회피가 §5.7.3 핵심 invariant

### 사용자 분석의 가치
사용자 분석이 정확히 짚은 3 약점 (orchestration 약함 / memory scope
분리 약함 / worker abstraction 약함) 은 모두 본 트랙의 4 phase 가
순차적으로 해소한다:
- orchestration → Phase 2 (Planner / Verification)
- memory scope → Phase 3 (§5.7.6 의 코드)
- worker abstraction → §5.7.3 roles-vs-workers 룰 박은 후 자연 분해

---

## 3. PR 시퀀스 (2026-05-17 갱신)

### Phase 0 — Infrastructure (4 PR, **전부 머지**)
| PR | 산출물 | 머지 |
|---|---|---|
| **Pre-L0** | `docs/ARCHITECTURE.md §5.7.2` 단락 (backends + trace_schema, `architecture` 라벨) | #282 ✓ |
| **L0** | `core/reasoning/trace_schema.py` + `core/reasoning/backends/` (Backend Protocol + registry + ollama_local / claude_code_cli). wiring 0 | #283 ✓ |
| **L1** | 12 `call_gemma` 호출 site 에 `trace_synth_call` wrap. audit row 발생 시작 | #284 ✓ |
| **L2** | `scripts/replay_trace.py` — trace_id 로 reasoning sequence 재구성 | #285 ✓ |

### Phase 1 — Retrieval Intelligence (3 PR 머지, PR-3/4 선택 잔여)
| PR | 산출물 | 디폴트 | 머지 |
|---|---|---|---|
| **PR-1** Reranker | `core/retrieval/rerank.py` — cross-encoder `ms-marco-MiniLM-L-6-v2` ~80 MB. `core/reasoning/pipeline_loops.py:run_loop_0_retrieve` 에서 wiring | **ON** (`JAMES_DISABLE_RERANK=1` 로 끄기) | #286 ✓ |
| **PR-2** Query rewriter | `core/retrieval/query_rewriter.py` — backend registry 통해 LLM rewrite | **OFF** (`JAMES_ENABLE_QUERY_REWRITE=1`) | #287 ✓ |
| **split** | `pipeline.py` 33.7 → 15 KB. `pipeline_loops.py` / `pipeline_synth.py` 추출 | — | #288 ✓ |
| ~~**PR-3** Hybrid search~~ | 현재 `core/orchestrator` 가 이미 BM25+vector hybrid — formalize 추후 필요 시 | — | 본 트랙 out of scope |
| ~~**PR-4** Adaptive retrieval~~ | spot-check 결과 후 결정 | — | deferred |

### Phase 2 — Reasoning Depth (4 PR 머지 완료)
| PR | 산출물 | 디폴트 | 머지 |
|---|---|---|---|
| **PR-5** Reflection loop | `core/reasoning/reflect.py` — draft → critique → revised | **OFF** (`JAMES_ENABLE_REFLECT=1`) | #289 ✓ |
| **PR-6** Verification engine | `core/reasoning/verify.py` — security_validator (휴리스틱) + fact_checker (LLM, 별 env gate) | **OFF** (`JAMES_ENABLE_VERIFY=1` + 옵션 `JAMES_ENABLE_FACT_CHECK=1`) | #290 ✓ |
| **PR-7** Planner | `core/reasoning/planner.py` + `pipeline_synth.py:65` wiring — 2~5 subtask 분해, system_prompt prepend | **OFF** (`JAMES_ENABLE_PLANNER=1`) | ✓ (이미 머지됨; 본 handover 갱신 누락이었음) |
| **PR-8** Tool Router | `core/reasoning/tool_router.py` — read/write 분리, write 는 CR-E 자동 wrap. wiring 0 (인프라) | — | #295 ✓ |

### Phase 3 — Memory Expansion (PR-9a + PR-9b 머지)
| PR | 산출물 | 머지 |
|---|---|---|
| **PR-9a** Episodic store | `core/memory/episodic.py` — session-scoped event log + SQLite schema + 24 tests | ✓ (이미 머지됨) |
| **PR-9b** Episodic wiring | 4 cognitive stage 의 `record_event()` + ContextVar 전파 + cross-turn 컨텍스트 주입 + `GET /admin/episodic/{session_id}` | ✓ (본 PR) |
| **PR-10a** Working memory infra | `core/memory/working.py` — turn-scoped scratch (in-process dict, ContextVar 재활용). wiring 0 | ✓ (본 PR) |
| **PR-10b** Working memory wiring | engine.query finally hookup (이번 PR — minimal: clear_turn + ContextVar reset). 의미 있는 read 측 wiring 은 PR-12 Context Optimizer 에서 진행. write 측 stash 는 그때 동반. | ✓ (본 PR) |
| **PR-11** (선택) Long-term graph evolution | entity 외 **event 노드** 추가 — `docs/design/v0.3-graph-evolution.md`. PR-11a~e 시퀀스 분할 | design ✓ / code pending |

### Phase 4 — Controlled Multi-Agent
- 사이클 9 CR-E 가 이미 Orchestrator/Approver 구조 → 그 위에 확장
- 룰: Orchestrator + Domain Specialist + Verification Agent + Security Validator + Final Synthesizer **5 종 만**
- **agent sprawl 금지** 를 ARCHITECTURE.md 에 명시 (이번 PR 에서 추가)

---

## 4. ARCHITECTURE.md 변경 (본 PR)

§5.7 **Cognitive Middleware Layer** 신설:
- 위치: `Retrieval` 와 `Reasoning Loop` 사이
- 7 구성요소: Planner / Query Rewriter / Reflection / Verification / Tool Router / Memory Manager / Security Reasoner / Context Optimizer
- Trust zone: cognitive middleware 는 **medium** trust (PolicyEngine 위, LLM synthesis 아래). reflection / verification 결과를 audit log 에 기록
- agent sprawl 금지 invariant
- 의존성 방향: cognitive middleware → retrieval 만 (역방향 금지)

§4 의 layer 다이어그램은 본 PR 에서 갱신하지 않는다 (별 PR로 ASCII 정렬). §5.7 안에 별 다이어그램만 추가.

---

## 5. CLAUDE.md gate 정합

| Rule | 본 트랙에서의 의미 |
|---|---|
| #1 도메인 분화 금지 | cognitive middleware 는 platform 레이어. 도메인 reasoning agent (legal / food / retail) 는 v1.0 이후 |
| #2 bench numbers | retrieval / graph / reasoning 을 만지는 모든 PR (Phase 1 + 2 의 대부분) 은 STEP 7 bench 필수 |
| #3 자가-진화 게이트 | Verification engine 이 CR-E 와 통합되어 approver_username 게이트 유지 |
| #4 architecture 변경 | 본 PR 이 §5.7 추가 — `architecture` 라벨 |
| #5 20 KB 모듈 | Phase 별로 새 파일 분할. `core/reasoning/`, `core/retrieval/` 하위 디렉토리로 자연 분리 |

---

## 6. 사용자 액션 대기 (이번 핸드오버 머지 후)

1. **추가 피드백 수렴** — 사용자가 본 핸드오버 + §5.7 검토 + 추가 입력
2. **Phase 1 PR-1 (Reranker) 진입 결정** — bench 시나리오 + 모델 선택 확정 후 코드 작업 시작
3. **사이클 8 라이브 검증** (#273 / #274) — 병행. cascade 안전성 게이트

---

## 7. 디퍼된 항목 (본 트랙과 무관)

- 사이클 4 CLA Track B — 외부 기여자 트리거 발생 시
- 사이클 7 Plugin API — v0.3.x 후반 또는 v0.4
- 사이클 10 다국어 호환 — 점진, side track
- Phase E follow-up UI (per-source 편집 / node 편집) — side track
- Surgical triple cascade (Phase D 정제) — side track

---

## 8. 한국어 요약

JAMES 가 RAG chatbot 에서 **secure cognitive operating system** 으로
진화한다. 코어 (graph / ontology / security) 는 그대로 두고, retrieval
강화 + reasoning middleware + memory 확장 + controlled multi-agent 의
4 phase 로 점진 확장. 사이클 7 (Plugin API) 는 외부 기여자 트리거가
없으므로 슬립. CR-E 는 verification engine 과 합쳐 진행. 실제 코드
작업은 사용자 추가 피드백 후 시작.
