# SPEC-20260412233043: Cross-Agent Unified Memory

**Status**: Approved  
**Date**: 2026-04-12  
**Author**: epicsagas

## Goal

`~/.harness/memory/`에 모든 코딩 에이전트(Claude Code, Codex, Gemini, Cursor, Cline 등)가 공유·질의할 수 있는 통합 메모리 시스템을 구축하고, 지식 그래프를 웹뷰로 시각화·검색·편집할 수 있도록 한다.

## Scope

### 포함
- `~/.harness/memory/` — 에이전트 공통 메모리 저장소 (Markdown + JSON)
- 메모리 CRUD CLI (`harness mem` 서브커맨드 — 기존 Rust 바이너리 확장)
- 지식 그래프 생성 엔진 (노드: 개념/프로젝트/패턴, 엣지: 관계)
- 이중 웹뷰 서버:
  - 기본: Rust 바이너리 내장 (`harness mem serve`)
  - 대안: Node.js 모드 (`harness mem serve --node`)
- 웹뷰 CRUD UI (노드 추가/편집/삭제, 엣지 수동 연결)
- 에이전트별 어댑터 (Claude Code hooks, Gemini hooks, Cursor rules 등)
- 기존 프로젝트 메모리 마이그레이션 (`harness mem migrate`)

### 제외
- 클라우드 동기화 / 외부 DB 연동
- 실시간 다중 사용자 협업
- LLM 임베딩 기반 벡터 검색 (추후 확장)

## Requirements

### R1. 저장소 구조

```
~/.harness/memory/
  nodes/          # 개념·패턴·프로젝트 노드 (YAML frontmatter + Markdown body)
  edges.jsonl     # 방향 그래프 엣지 (source, target, relation, weight, ts)
  index.json      # 빠른 조회용 역색인 (태그, 타입, 프로젝트)
  graph.json      # 캐시된 전체 그래프 (rebuild 시 갱신)
```

### R2. 노드 스키마

```yaml
---
id: uuid-v4
type: concept | pattern | project | decision | error
title: "string"
tags: [tag1, tag2]
projects: [project-slug]
agents: [claude-code, codex, gemini]
created: ISO8601
updated: ISO8601
---
Markdown body
```

### R3. 엣지 스키마

```jsonl
{"id":"uuid","source":"node-id","target":"node-id","relation":"uses|extends|conflicts|replaces|related|caused_by","weight":1.0,"ts":"ISO8601"}
```

### R4. CLI 인터페이스

| 명령 | 설명 |
|------|------|
| `harness mem add --title --type --tags --body` | 노드 추가 |
| `harness mem edit <id>` | 노드 편집 |
| `harness mem delete <id>` | 노드 삭제 |
| `harness mem query --tag --type --project --agent` | 필터 쿼리 |
| `harness mem search <keyword>` | ripgrep 전문 검색 |
| `harness mem related <id> --depth=2` | 그래프 탐색 |
| `harness mem link <src> <dst> --relation` | 엣지 수동 추가 |
| `harness mem graph rebuild` | graph.json 재생성 |
| `harness mem serve [--port=7700] [--node]` | 웹뷰 서버 실행 |
| `harness mem context --project=<slug>` | 세션 시작 시 관련 메모리 주입 |
| `harness mem validate` | 손상 노드 감지 |
| `harness mem migrate --project=<slug> [--all] [--dry-run]` | 기존 메모리 마이그레이션 |

- 쿼리 응답 목표: **< 50ms** (노드 1000개 기준)

### R5. 웹뷰 서버 — 이중 모드

**Rust 내장 모드** (기본):
- 정적 HTML/JS/CSS → `include_str!` 임베드
- `GET /api/graph`, `GET /api/search?q=`, `GET /api/nodes/:id`
- `POST /api/nodes`, `PUT /api/nodes/:id`, `DELETE /api/nodes/:id`
- `POST /api/edges`, `DELETE /api/edges/:id`

**Node.js 모드** (`--node`):
- `integrations/` 기존 JS 인프라 활용
- 동일한 API 엔드포인트 구현

### R6. 웹뷰 UI

- **그래프 시각화**: D3.js force-directed graph
  - 노드 클릭 → 상세 패널 (Markdown 렌더링)
  - 노드 더블클릭 → 인라인 편집 모드
  - 드래그로 엣지 연결
- **검색바**: 실시간 필터 (제목, 태그, 본문 키워드)
- **필터 패널**: type, agent, project, tag
- **CRUD UI**: 노드 추가 폼, 편집 폼, 삭제 확인, 엣지 연결 드롭다운

### R7. 에이전트 통합

- **Claude Code**: `PostToolUse` hook → 결정/패턴 감지 시 자동 `harness mem add`
- **Gemini**: `settings.json` hook → `harness mem add` 호출
- **Cursor**: `hooks.json` → mem add 삽입
- **Cline**: `PostToolUse` 훅 스크립트에 mem add 삽입
- 세션 시작 시 `harness mem context --project=<slug>` 로 관련 메모리 에이전트 컨텍스트 주입

### R8. 마이그레이션

- `~/.harness/projects/{slug}/memory/*.md` → `~/.harness/memory/nodes/` 변환
- frontmatter 자동 생성: id(uuid), type(decision 추론), projects([slug]), agents([]) 
- `--dry-run`: 실제 파일 쓰기 없이 변환 결과 미리보기
- `--all`: 전체 프로젝트 일괄 처리

### R9. 안정성

- 쓰기: atomic (tmp → rename), 동시 접근 시 파일 락
- 읽기: index.json 캐시 우선, miss 시 nodes/ 풀스캔
- `harness mem validate`: YAML 파싱 오류 노드 리포트

## Acceptance Criteria

- [ ] `harness mem add/query/search/related/serve/validate/migrate` 명령 동작
- [ ] 쿼리 응답 < 50ms (노드 1000개 기준)
- [ ] `harness mem serve` — Rust 내장 모드 웹뷰 동작
- [ ] `harness mem serve --node` — Node.js 모드 동작
- [ ] 웹뷰 `localhost:7700` 그래프 렌더링 + 실시간 검색 동작
- [ ] 웹뷰에서 노드 추가/편집/삭제/엣지 연결 동작
- [ ] Claude Code `PostToolUse` 훅 자동 메모리 기록
- [ ] Gemini, Cursor 어댑터 구현 (최소 3개 에이전트)
- [ ] `harness mem migrate --all --dry-run` 동작
- [ ] `harness mem validate` 손상 노드 감지

## Technical Notes

- **구현 언어**: Rust (기존 `epic-harness` 바이너리 확장) + 웹뷰 정적 번들
- **웹뷰**: D3.js force-directed, marked.js (Markdown 렌더링), 단일 HTML 파일 번들
- **파일 포맷**: YAML frontmatter + Markdown (기존 evolved skill 구조와 동일)
- **Rust 의존성**: `serde_yaml`, `uuid`, `tiny_http` 또는 `axum` (웹서버)
- **전역 vs 프로젝트 메모리**: `~/.harness/projects/{slug}/memory/` 유지, 전역 `~/.harness/memory/`와 분리. 쿼리 시 `--scope=global|project|all` 선택 가능
