memorytrace 0.4.0__tar.gz → 0.5.0__tar.gz

{memorytrace-0.4.0 → memorytrace-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorytrace
-Version: 0.4.0
+Version: 0.5.0
 Summary: AI agent memory system with SQLite+FTS5, MCP integration, and quality gates
 Project-URL: Homepage, https://github.com/aop60003/default
 Project-URL: Issues, https://github.com/aop60003/default/issues

memorytrace-0.5.0/docs/06-reference-comparison/01-overview.md

@@ -0,0 +1,77 @@
+# ?? ?? vs Engram 비교 분석
+
+> **원격**: ?? ???? ????? (?? ?? ??)
+> **로컬**: Engram (v0.3.1, PyPI: `memorytrace`)
+> **분석일**: 2026-04-16
+
+## 프로젝트 개요
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| **한줄 요약** | Zero-dependency compound knowledge system for AI agents | AI 에이전트를 위한 지속적·구조적·신뢰할 수 있는 메모리 시스템 |
+| **코어 구조** | 단일 클래스 모놀리스 (`core.py` ~4,362줄) | 모듈형 아키텍처 (models/storage/search/quality/session/cli + 12개 feature service) |
+| **저장소** | Plain Markdown 파일 (디렉토리 기반) | SQLite + FTS5 (+ 선택적 Markdown 내보내기) |
+| **검색** | difflib + IDF + fuzzy (stdlib) | FTS5 BM25 + Reranker + 선택적 시맨틱 |
+| **의존성** | Zero (stdlib only) | Zero core (LLM/semantic은 optional extras) |
+| **에이전트 통합** | CLI + Python SDK | MCP 서버 + CLI + Python SDK |
+| **출력 방식** | `print()` 직접 출력 | 구조화된 객체 반환 (core에 print 없음) |
+| **스키마 관리** | 없음 (파일 기반) | 11단계 마이그레이션 시스템 |
+| **언어 지원** | EN/KR/CN/JP NER | EN/KR/CN/JP NER (한국어 문맥 기반으로 개선) |
+| **테스트** | 7개 파일 | 30+ 파일, 기능별 디렉토리 분리 |
+| **라이선스** | MIT | MIT |
+
+## 디렉토리 구조 비교
+
+### ?? ??
+
+```
+src/reference/
+├── __init__.py
+├── core.py            # ~4,362줄, 전체 로직이 하나의 클래스에 집중
+├── cli.py             # ~600줄, argparse CLI 래퍼
+├── stopwords.json     # ~813줄 (KR/CN/JP 불용어)
+└── templates/
+    ├── RESOLVER.md    # MECE 분류 결정 트리
+    └── TEMPLATES.md   # 엔티티/회사 페이지 템플릿
+```
+
+### Engram
+
+```
+engram/
+├── models/          # 20개 순수 데이터클래스 (entity, fact, source, relation, session, ...)
+├── storage/         # SQLite+FTS5 백엔드 + 마이그레이션 (v1~v11) + Markdown 내보내기
+├── search/          # FTS5 BM25 + 시맨틱 + 하이브리드 + 리랭커 + 토크나이저
+├── extraction/      # regex NER (EN/KR/CJK) + LLM 추출기
+├── quality/         # confidence, conflict, decay, PII, diagnostics, gate
+├── session/         # manager, brief, context, working_memory
+├── cli/             # app.py, formatters.py, simple.py
+├── integrations/    # MCP 서버 + Python SDK
+├── safety/          # 경로 안전성 검증
+├── debug/           # 가설 기반 디버그 서비스
+├── decisions/       # 의사결정 추적 서비스
+├── explanations/    # 프로비넌스 추적 빌더
+├── intake/          # 단계적 쓰기 파이프라인
+├── maintenance/     # 유지보수 실행 기록
+├── references/      # 백링크 프로젝션
+├── snapshots/       # 시점 백업 + 시간여행 쿼리
+├── freshness/       # 신선도 검증 (미커밋)
+├── governance/      # 엔티티 거버넌스 (미커밋)
+├── jobs/            # 작업 큐 (미커밋)
+├── recommendations/ # 추천 서비스 (미커밋)
+├── retention/       # 보존 정책 (미커밋)
+└── scopes/          # 스코프 메모리 (미커밋)
+```
+
+## 문서 구성
+
+| 문서 | 내용 |
+|------|------|
+| [01-overview.md](./01-overview.md) | 프로젝트 개요 및 구조 비교 (이 문서) |
+| [02-architecture-changes.md](./02-architecture-changes.md) | 핵심 아키텍처 변경 분석 (저장소, 모듈화, 검색, 품질 게이트, MCP) |
+| [03-shared-features.md](./03-shared-features.md) | 공유 기능 비교 (양쪽 모두 존재하는 기능의 구현 차이) |
+| [04-new-features.md](./04-new-features.md) | Engram 신규 기능 유효성 분석 (6개 신규 기능) |
+| [05-missing-features.md](./05-missing-features.md) | ?? ??에만 존재하는 기능 (Engram 누락 분석) |
+| [06-risks-and-recommendations.md](./06-risks-and-recommendations.md) | 리스크, 개선 권고, 결론 |
+| [07-practical-feature-selection.md](./07-practical-feature-selection.md) | Engram에 실질적으로 필요한 기능만 다시 추린 결론 문서 |
+

memorytrace-0.5.0/docs/06-reference-comparison/02-architecture-changes.md

@@ -0,0 +1,208 @@
+# 핵심 아키텍처 변경 분석
+
+?? ?? → Engram 전환에서 발생한 5가지 핵심 아키텍처 변경을 분석한다.
+
+---
+
+## 1. 저장소: Markdown 파일 → SQLite+FTS5
+
+### 변경 내용
+
+?? ??는 디렉토리 기반 Markdown 파일에 모든 데이터를 저장한다. 엔티티는 `entities/`, `live-notes/` 디렉토리에, 의사결정은 `decisions/`에, 세션 이벤트는 `sessions/`에 JSONL로 기록된다.
+
+Engram은 SQLite 단일 파일에 20+ 테이블로 구조화된 스키마를 사용한다. WAL 모드, 외래키 강제, busy_timeout 5000ms가 적용되며, 선택적으로 Markdown 내보내기(`MarkdownExporter`)를 지원한다.
+
+### 평가
+
+| 항목 | 평가 |
+|------|------|
+| **유효성** | **유효함** — ACID 트랜잭션, 원자적 쓰기, 서브밀리초 쿼리, FTS5 전문 검색 지원 |
+| **필요성** | **필수** — FTS5 전문 검색, 충돌 검사의 원자적 처리, 동시 접근은 파일 기반으로 불가능 |
+| **품질** | **보통** |
+
+### 구현 상세
+
+**강점**:
+- `threading.local()` 기반 thread-local 연결로 SQLite 스레딩 이슈 방지
+- 모든 쓰기 작업에 명시적 rollback 처리
+- 파일 생성 시 `0o600` 권한 설정 (보안 위생)
+- FTS5 인덱스가 entity name, type, facts, state, summary, relation targets를 포괄
+- 노트 중복 검출에 SHA-256 해시 컬럼 + 인덱스 사용
+
+**우려점**:
+- `sqlite_store.py`가 2,113줄 — 20+ 테이블의 CRUD를 하나의 클래스에서 처리하는 God Object
+- `_SCHEMA_SQL` 상수와 마이그레이션이 동일 스키마를 별도 관리하는 이중진실(dual-truth) 문제
+- `_row_to_fact()`가 `"scope_id" in row.keys()` 같은 마이그레이션 상태 인식 코드를 포함 (누수 추상화)
+
+### 트레이드오프
+
+| 관점 | Markdown (?? ??) | SQLite (Engram) |
+|------|---------------------|-----------------|
+| 가독성 | 사람이 직접 파일 탐색기로 열람 가능 | CLI/API 통해서만 접근 (Markdown 내보내기 선택적) |
+| Git 추적 | 파일별 diff/blame 자연스러움 | 바이너리 파일이라 diff 불가 |
+| 쿼리 성능 | 파일 스캔 필요 (O(N)) | 인덱스 기반 서브밀리초 (O(log N)) |
+| 트랜잭션 | 없음 (부분 쓰기 가능) | ACID 보장 |
+| 동시 접근 | 파일 잠금 필요 | WAL 모드로 동시 읽기/쓰기 지원 |
+
+---
+
+## 2. 모놀리스 → 모듈형 아키텍처
+
+### 변경 내용
+
+?? ??는 `?? ??` 단일 클래스(~4,362줄)에 모든 기능을 포함한다.
+
+Engram은 `MemoryEngine`(~1,922줄)이 15+ 서비스를 조합하는 Facade 패턴을 사용한다. `StorageBackend` Protocol로 인터페이스를 추상화했다.
+
+### 평가
+
+| 항목 | 평가 |
+|------|------|
+| **유효성** | **유효함** — Protocol 기반 인터페이스 추상화, 의존성 주입 패턴 적용 |
+| **필요성** | **부분적** — 코어(storage/search/quality/session) 분리는 필수. Feature service 증식은 과잉 위험 |
+| **품질** | **보통** |
+
+### 구현 상세
+
+**강점**:
+- `StorageBackend` Protocol에 `@runtime_checkable` 적용 → 테스트 시 mock 백엔드 사용 가능
+- `__init__`에서 모든 서비스를 명시적 DI로 생성 (전역 상태, 서비스 로케이터 없음)
+- 추출기와 Markdown 내보내기는 lazy 초기화 → LLM 의존성 불필요 시 로딩 안 함
+- 검색 엔진 graceful degradation: hybrid → semantic → FTS5
+
+**우려점**:
+- `engine.py` 1,922줄, 70+ public 메서드 — 여전히 God Class
+- 일부 서비스는 eager 생성(`__init__`), 일부는 lazy 생성(호출 시 `_maintenance_service()`) → 비일관
+- `models/` 패키지에 20개 파일 — `view.py`, `brief.py`, `explanation.py` 같은 얇은 래퍼는 서비스와 co-locate 가능
+
+---
+
+## 3. 검색: difflib+regex → FTS5 BM25+Reranker
+
+### 변경 내용
+
+?? ??는 stdlib 기반 검색을 사용한다:
+- 정확 매칭: 파일명/내용 substring 검색
+- IDF 가중 토큰 스코어링: 희소 토큰에 높은 점수
+- Fuzzy 매칭: `difflib.SequenceMatcher`
+- Phrase 보너스, 제목 보너스, 최신성 보너스
+
+Engram은 SQLite FTS5 기반 검색을 사용한다:
+- BM25 스코어링 (컬럼별 가중치)
+- CJK/한국어 토크나이저
+- 세션 컨텍스트 기반 리랭킹
+- 선택적 시맨틱/하이브리드 검색
+
+### 평가
+
+| 항목 | 평가 |
+|------|------|
+| **유효성** | **유효함** — FTS5 BM25는 TF-IDF 포화, 문서 길이 정규화를 기본 지원 |
+| **필요성** | **필수** — 규모 있는 메모리 시스템에 적절한 전문 검색은 필수 |
+| **품질** | **우수** |
+
+### BM25 컬럼 가중치
+
+```python
+_BM25_WEIGHTS = (0.0, 10.0, 1.0, 3.0, 2.0, 5.0)
+# entity_id: 0, entity_name: 10, entity_type: 1, fact_text: 3, state_text: 2, summary: 5
+```
+
+엔티티 이름(10x)에 최고 가중치, 요약(5x), 팩트 텍스트(3x) 순서.
+
+### 리랭킹 부스트
+
+| 조건 | 부스트 |
+|------|--------|
+| 세션에서 활성 엔티티 | +0.6 |
+| 최근 접근 엔티티 | +0.2 |
+| 선호 엔티티 | +0.4 |
+| 목표 타입 선호 (예: meeting_prep → person) | +0.25 |
+
+### 검색 파이프라인 (Engram)
+
+```
+쿼리 → 토크나이저(CJK 지원) → FTS5 BM25 → 신선도 페널티 적용 →
+스코프 필터링 → 보존 정책 필터링 → 세션 리랭킹 → 프로비넌스 추적 → 결과 반환
+```
+
+---
+
+## 4. Quality Gate 도입
+
+### 변경 내용
+
+?? ??에는 쓰기 경로에 품질 검증이 없다. Engram은 5단계 `QualityGate`를 모든 쓰기 경로에 적용한다.
+
+### 평가
+
+| 항목 | 평가 |
+|------|------|
+| **유효성** | **유효함** — PII 마스킹, 중복 검출, 충돌 감지가 실질적 문제 해결 |
+| **필요성** | **필수** (PII/중복) / **Nice-to-have** (전체 진단 스위트) |
+| **품질** | **우수** |
+
+### 5단계 파이프라인
+
+```
+1. 신뢰도 스코어링
+   base_trust(source_type) × source_confidence × extraction_multiplier
+   source: direct_speech=0.95, document=0.90, API=0.85
+   extraction: LLM=1.0, manual=1.0, regex=0.7
+
+2. 메모리 타입 분류
+   predicate 키워드 기반 IDENTITY/PREFERENCE/EPISODIC/TRANSIENT 자동 분류
+
+3. PII 탐지 및 마스킹
+   - 신용카드 (Luhn 알고리즘 검증)
+   - 주민등록번호, SSN
+   - API 키, 이메일
+   - 한국 전화번호, 한국 주민등록번호
+   마스킹 결과: [credit_card:19chars] (원본 PII 절대 저장 안 함)
+
+4. 중복 검출
+   동일 entity + predicate + object (정규화, 대소문자/관사 제거)
+
+5. 충돌 검출
+   동일 entity + predicate, 다른 object → 신뢰도 차이 기반 자동 해소
+   - supersede: 새 팩트 신뢰도 ≫ 기존
+   - keep_old: 기존 신뢰도 ≫ 새 팩트
+   - manual_review: 신뢰도 차이 작음
+```
+
+---
+
+## 5. MCP 통합
+
+### 변경 내용
+
+?? ??는 CLI와 Python SDK만 제공한다. Engram은 MCP(Model Context Protocol) 서버를 추가하여 Claude Code와 네이티브 통합한다.
+
+### 평가
+
+| 항목 | 평가 |
+|------|------|
+| **유효성** | **유효함** — MCP는 Claude Code의 네이티브 통합 프로토콜 |
+| **필요성** | **필수** — MCP 없으면 에이전트가 CLI로 셸아웃 해야 함 |
+| **품질** | **보통** — 기본 CRUD는 커버하나 확장 여지 있음 |
+
+### 제공 MCP 도구 (7개)
+
+| 도구 | 기능 |
+|------|------|
+| `memory_search` | BM25 검색 (토큰 버짓 제한) |
+| `memory_store` | 정보 저장 (source type, confidence) |
+| `memory_get_entity` | 엔티티 조회 + 팩트 |
+| `memory_list_entities` | 필터링된 엔티티 목록 |
+| `memory_session_start` | 세션 시작 + 컨텍스트 |
+| `memory_session_end` | 세션 종료 + 요약 |
+| `memory_resolve_conflict` | 충돌 해소 |
+
+### 누락된 MCP 도구 (확장 권고)
+
+- `memory_health` — 진단/헬스체크
+- `memory_maintenance` — 유지보수 실행
+- `memory_brief` — 엔티티/세션 브리프
+- `memory_governance` — 거버넌스 후보 조회/해소
+- `memory_retention` — 보존 정책 관리
+

memorytrace-0.5.0/docs/06-reference-comparison/03-shared-features.md

@@ -0,0 +1,145 @@
+# 공유 기능 비교
+
+양쪽 모두 존재하는 9개 핵심 기능의 구현 차이를 비교한다.
+
+---
+
+## 1. 엔티티 관리
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 저장 | Markdown 파일 (entities/, live-notes/) | SQLite `entities` 테이블 |
+| 상태 관리 | 마크다운 섹션 파싱 | 구조화된 `EntityState` (role, affiliation, location, email, custom) |
+| 계층(Tier) | core/recall/archival | 동일 — `Tier` enum |
+| 별칭 | 없음 | `aliases` 리스트 + `get_entity_by_name()` 별칭 해소 |
+| 병합 | 없음 | `merge_entities()` — 팩트/관계/별칭/상태 전체 이전 |
+| 압축 | 없음 | `compact_entity()` — predicate별 최선 팩트만 보존 |
+| 브리프 | `brief()` — 마크다운 요약 | `EntityBrief` — 상위 팩트, 관련 엔티티, 최근 노트, 세션, 미해결 충돌 합성 |
+| 접근 추적 | 없음 | `touch()` 접근 카운트 + 타임스탬프 |
+
+**판정**: **대폭 개선** — SQL 쿼리가 파일 스캔 대체, 엔티티 병합/압축은 진정한 운영 기능.
+
+---
+
+## 2. NER/추출
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 구조 | `core.py` 내 인라인 | 모듈형 (`extraction/regex_extractor.py`, `ner/english.py`, `ner/korean.py`, `ner/cjk.py`) |
+| 영어 NER | Title Case 이름 (2-3 단어) | 동일 + 조직 접미사, 블록리스트 확장 |
+| 한국어 NER | 한글 2-4자 + 성씨 시작 | **문맥 기반**: 이름+존칭, 소개 패턴, 2음절+조사, 3음절+상위10 성씨. 90+ 성씨 |
+| CJK NER | 중국 100성씨, 일본 85성씨 | 동일 접근 |
+| 불용어 | `stopwords.json` (813항목) | 언어별 모듈 내 `frozenset`/`tuple` |
+| 팩트 추출 | `extract_facts_registry()` | `regex_extractor.py` — 팩트 + 관계 통합 추출 |
+| LLM 추출 | 없음 | `llm_extractor.py` — 선택적 플러그인 |
+| 인터페이스 | 없음 | `Extractor` Protocol — 백엔드 교체 가능 |
+
+**판정**: **개선** — 특히 한국어 NER이 "모든 2-4자 한글"에서 "문맥 증거 기반"으로 정밀도 대폭 향상.
+
+---
+
+## 3. 충돌 검출
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 탐지 | 동일 엔티티의 모순 팩트 | 동일 entity + predicate + 다른 object |
+| 해소 전략 | newest, confidence, keep-both, prompt | accept_new, keep_old, merge (양쪽 보존) |
+| 자동 해소 | 없음 | 신뢰도 차이 기반 자동 해소 (임계값 설정 가능) |
+| 영속화 | 메모리 내 + `CONFLICTS.md` | SQLite `conflicts` 테이블 |
+| 변증법 합성 | 모순을 합성된 관점으로 통합 | **없음** — merge는 양쪽을 그대로 보존 |
+| 대화형 해소 | `prompt` 전략 (사용자에게 질문) | **없음** |
+
+**판정**: **동등~개선** — 자동 해소와 영속화는 개선. 변증법 합성과 대화형 해소는 상실.
+
+---
+
+## 4. 디버그 서비스
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 워크플로우 | OBSERVE → HYPOTHESIZE → EXPERIMENT → CONCLUDE | 동일 (start → hypothesis → evidence → conclude) |
+| 저장 | `debug/` 디렉토리에 Markdown 파일 | SQLite 3개 테이블 (`debug_sessions`, `debug_hypotheses`, `debug_evidence`) |
+| 가설 상태 | open/confirmed/rejected | 동일 + abandoned |
+| 증거 분류 | 없음 (텍스트만) | supports/contradicts/neutral |
+| PII 마스킹 | 없음 | 모든 텍스트 필드에 PII 마스킹 |
+| 검색 | `search_rejected_hypotheses()` | `search_hypotheses()` (전체 검색 가능) |
+| 2-fail 경고 | 2번 기각 후 자동 경고 | 없음 (별도 구현 필요 시 추가 가능) |
+
+**판정**: **개선** — SQL 영속화, PII 마스킹, 증거 분류, 검색 가능한 가설 이력.
+
+---
+
+## 5. 스냅샷 / 시간여행
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 스냅샷 생성 | 매니페스트 (해시, 크기, 요약, 섹션, 팩트, 링크) | `sqlite3.Connection.backup()` + gzip 압축 |
+| 스냅샷 내 검색 | 없음 (매니페스트만) | 스냅샷 DB를 읽기 전용 열어 FTS5 검색 |
+| 시간여행 | `time_travel(query, date)` — 임의 시점 쿼리 | `search_at(snapshot_id, query)` — 스냅샷 ID 필요 |
+| 엔티티 이력 | `snapshot_entity(name)` — 스냅샷 간 엔티티 추적 | `get_entity_at(snapshot_id, name)` |
+| 스냅샷 비교 | `snapshot_diff()` | `diff(a_id, b_id)` — 엔티티/팩트/노트 delta |
+| 보안 | 없음 | `0o600` 파일 권한, 경로 순회 공격 방지 |
+
+**판정**: **개선** — 실제 DB 백업, 스냅샷 내 FTS5 검색, 보안 강화. 다만 임의 시점 쿼리 대신 명시적 스냅샷 ID가 필요하여 워크플로우가 약간 무거움.
+
+---
+
+## 6. 세션 / 작업 메모리
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 세션 관리 | JSONL 이벤트 로그 | `SessionManager` — 시작/종료, 엔티티 접근/수정 추적, 이벤트 로깅 |
+| 작업 메모리 | 채널/태스크/에이전트별 컨텍스트 | `WorkingMemory` — 활성 엔티티(최대 50), 최근 쿼리(최대 20), 인메모리 |
+| 채널 컨텍스트 | `channel_save/load/update()` 영속 | **없음** — WorkingMemory는 세션 종료 시 소멸 |
+| 태스크 관리 | `task_start/update/complete/delegate()` | **없음** (별도 태스크 서비스 없음) |
+| 에이전트 핸드오프 | `agent_handoff()` — 에이전트 간 메모리 이전 | **없음** |
+| 컨텍스트 캐리오버 | 이전 1개 세션 | 최근 5개 세션 엔티티 접근 이력 집계 |
+| PII 마스킹 | 없음 | 세션 이벤트에 PII 마스킹 |
+| 스코프 | 없음 | `scope_id` 기반 네임스페이스 격리 |
+
+**판정**: **단일 에이전트는 개선** — 풍부한 컨텍스트 캐리오버, PII 마스킹, 스코프. **멀티 에이전트는 후퇴** — 핸드오프와 채널 영속 컨텍스트 누락.
+
+---
+
+## 7. 의사결정 추적
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 추출 | `distill_decisions()` — 키워드 스캔 | `DecisionService` — 노트/세션/디버그 결론 스캔 |
+| 키워드 | 영어만 ("decided to", "we will", ...) | 이중언어 — 영어 + 한국어 ("결정", "하기로", "채택", "보류") |
+| 상태 | 없음 | ACTIVE / DRAFT (보류/draft/consider 키워드 기반) |
+| 영속화 | `decisions/` 디렉토리 Markdown | SQLite `decisions` 테이블 + SHA-256 핑거프린트 |
+| 엔티티 링크 | 없음 | `ReferenceService.match_entity_ids()` 자동 링크 |
+| 드리프트 감지 | 없음 | `projection_drift()` — 인덱싱 안 된 의사결정 소스 식별 |
+| 검증 | 없음 | 신선도 서비스 연계 (`verification_status`, `verification_due_at`) |
+
+**판정**: **대폭 개선** — 영속화, 이중언어, 엔티티 링크, 드리프트 감지, 검증 연계.
+
+---
+
+## 8. 헬스/진단
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 메트릭 수 | 5개 assertion | 8개 메트릭 |
+| 메트릭 목록 | (비공개 5개 체크) | 미해결 충돌, 소스 커버리지, 노후 팩트 비율, 검증 백로그, 노후 의사결정, 거버넌스 백로그, 고아 엔티티, 프로젝션 드리프트 |
+| 등급 | 알파벳 (A/B/C/D) | 가중 복합 점수 + 알파벳 (A/B/C/D) |
+| 실행 가능한 항목 | 없음 | `OpenLoop` — 종류, 심각도, 제목, 상세, 대상 ID, 권장 CLI 명령 |
+| 출력 | 터미널 텍스트 | `HealthReport.to_agent_context()` — 에이전트 소비용 Markdown |
+
+**판정**: **대폭 개선** — 8개 메트릭, 실행 가능한 OpenLoop, 에이전트 소비용 출력.
+
+---
+
+## 9. 메모리 타입
+
+| 관점 | ?? ?? | Engram |
+|------|----------|--------|
+| 타입 수 | 8종 | 4종 |
+| 타입 목록 | identity, belief, preference, relationship, skill, episodic, routine, transient | IDENTITY, PREFERENCE, EPISODIC, TRANSIENT |
+| 분류 방식 | `classify_memory_type()` | `classify_predicate()`, `classify_fact()` — 키워드 기반 |
+| 감쇠 연동 | 타입별 차등 감쇠 (상수) | 타입별 지수 감쇠 (반감기: IDENTITY 365일, PREFERENCE 180일, EPISODIC 30일, TRANSIENT 7일) |
+| 재분류 | 없음 | `reclassify_facts()` — 소급 재분류 |
+
+**판정**: **의도적 트레이드오프** — "4개 버킷으로 'identity는 잊지 말고 / 어제 기분은 빨리 폐기'를 표현하기에 충분. LLM 없이 분류 문제를 만들지 않는다." ?? ??의 8종은 라벨만 존재하고 차등 행동을 구동하지 않았으나, Engram의 4종은 각각 감쇠율을 직접 결정한다.
+

memorytrace-0.5.0/docs/06-reference-comparison/04-new-features.md

@@ -0,0 +1,198 @@
+# Engram 신규 기능 유효성 분석
+
+Engram에만 존재하는 6개 신규 기능(미커밋 상태)의 유효성, 필요성, 품질을 분석한다.
+
+---
+
+## 종합 판정
+
+```
+┌──────────────────────┬───────────┬───────────┬─────────┬─────────────────────────────────┐
+│ 기능                  │ 유효한가? │ 필요한가? │ 유용성  │ 판정                             │
+├──────────────────────┼───────────┼───────────┼─────────┼─────────────────────────────────┤
+│ Freshness            │ ✅ Yes    │ ✅ Yes    │ 4/5     │ KEEP — 검색 신뢰도 핵심         │
+│ Entity Governance    │ ✅ Yes    │ ✅ Yes    │ 4/5     │ KEEP — NER 중복 해소 필수       │
+│ Retention Policies   │ ✅ Yes    │ ✅ Yes    │ 4/5     │ KEEP — 감쇠/압축 보완 필수      │
+│ Scoped Memory        │ ✅ Yes    │ ✅ Yes    │ 4/5     │ KEEP — 멀티컨텍스트 필수        │
+│ Job Runner           │ ✅ Yes    │ ⚠️ Not yet│ 3/5     │ DEFER — 비동기 미활용           │
+│ Recommendations      │ ⚠️ Partial│ ❌ No     │ 2/5     │ DEFER — 시그널 재집계, 테스트 無 │
+└──────────────────────┴───────────┴───────────┴─────────┴─────────────────────────────────┘
+```
+
+---
+
+## 1. Freshness Verification (신선도 검증) — KEEP
+
+**파일**: `engram/freshness/service.py` (302줄), `engram/models/verification.py` (79줄)
+**테스트**: `tests/test_freshness/test_service.py` (2/2 통과)
+
+### 기능
+
+팩트와 의사결정의 신선도를 추적하는 검증 생명주기를 관리한다.
+
+```
+팩트/의사결정 저장 → verification_due_at 설정 (메모리 타입별 감쇠 정책 기반)
+                → 검색 시 만료 여부 확인 → 만료 시 VerificationRequest 자동 생성
+                → 해소: VERIFIED (재검증), STALE, RETRACTED, SUPERSEDED
+```
+
+- 검색 시 만료된 팩트에 **-0.30 점수 페널티** 자동 적용
+- "verify on read" 패턴: 전체 스캔 대신 검색 시점에 lazy하게 만료 감지
+- 요청 중복 방지: `find_open_verification_request()`로 동일 대상 재요청 방지
+
+### 유효성 분석
+
+**필요한 이유**: 장기 메모리에서 팩트 노후화는 불가피하다. 누군가의 직책이 바뀌거나, 프로젝트가 방향을 전환하거나, 의사결정이 번복된다. 신선도 추적 없이는 에이전트가 오래된 정보를 현재 사실처럼 자신 있게 제시한다.
+
+**설계 품질**: 평가(순수 로직 `FreshnessAssessment`)와 변경(요청 생성/해소)이 깔끔하게 분리되어 있다. `DecayPolicy`의 메모리 타입별 반감기를 재사용하므로 별도 설정 불필요.
+
+---
+
+## 2. Entity Governance (엔티티 거버넌스) — KEEP
+
+**파일**: `engram/governance/service.py` (288줄), `engram/models/governance.py` (65줄)
+**테스트**: `tests/test_governance/test_entity_governance.py` (4/4 통과)
+
+### 기능
+
+엔티티 중복을 탐지하고 해소하는 거버넌스 워크플로우를 제공한다.
+
+```
+generate_candidates() → O(n²) 페어와이즈 비교
+  ├─ MERGE: 정규화 이름 일치 또는 별칭 교차 매칭
+  ├─ ALIAS: 한쪽이 다른 쪽의 별칭 후보
+  └─ SPLIT: 동일 엔티티에 모순 속성 (role, affiliation, location, email)
+
+resolve_candidate()
+  ├─ approve → merge: merge_entities_by_id() 실행, 중복 alias 후보 자동 취소
+  ├─ approve → alias: 별칭 추가
+  └─ reject → 후보 기각
+```
+
+- 핑거프린트 기반 멱등 업서트: 동일 후보 재생성 방지
+- `limit=5000` 엔티티로 O(n²) 바운드
+
+### 유효성 분석
+
+**필요한 이유**: NER 기반 시스템에서 "Simon Kim" vs "S. Kim" vs "김시몬" 중복은 예견된 고빈도 문제다. Split 탐지("CTO"와 "HR Manager"를 동시에 가진 엔티티 = 동명이인 혼재)도 실질적 가치가 있다.
+
+**설계 품질**: `merge_fn` 콜백을 통한 느슨한 결합, 병합 후 중복 alias 후보 자동 정리 등 라이프사이클을 잘 고려한 설계.
+
+---
+
+## 3. Job Runner (작업 큐) — DEFER
+
+**파일**: `engram/jobs/service.py` (65줄), `engram/models/job.py` (27줄)
+**테스트**: `tests/test_jobs/test_service.py` (3/3 통과)
+
+### 기능
+
+SQLite 기반 영속 작업 큐. enqueue → lease → execute → mark_failed/complete.
+
+```
+enqueue(job_type, payload, max_attempts)
+  → lease(owner) — 원자적 작업 할당
+  → mark_failed() — 재시도 (max_attempts 미달) 또는 dead_letter
+```
+
+지원 작업 타입: `index_source`, `rebuild_references`, `rebuild_decisions`, `rebuild_projections`, `maintenance_run`
+
+### 유효성 분석
+
+**문제점**: 현재 `engine.py`에서 enqueue 후 **즉시 동기 실행**한다:
+```python
+# store() 메서드 내부
+self._job_runner.enqueue("index_source", ...)  # 작업 등록
+self._index_source(note_id)                     # 바로 실행
+```
+
+실질적으로 `jobs` 테이블은 실행 로그일 뿐 진정한 비동기 큐가 아니다. `run_jobs()` API는 존재하지만 호출하는 자동 스케줄러가 없다.
+
+**보류 사유**: 백그라운드 데몬이나 cron 기반 스케줄러가 도입될 때까지 불필요한 스키마 복잡도(테이블 + 인덱스)만 추가한다. 구현 자체는 깔끔하므로 코드를 유지하되 활성화는 보류.
+
+---
+
+## 4. Recommendations (추천 서비스) — DEFER
+
+**파일**: `engram/recommendations/service.py` (448줄), 모델은 `engram/models/retention.py`에 혼입
+**테스트**: **없음**
+
+### 기능
+
+4가지 추천을 현재 상태로부터 계산한다:
+
+| 추천 종류 | 소스 |
+|----------|------|
+| `STALE_DECISION` | verification_due_at 경과 + 열린 요청 없는 의사결정 |
+| `OPEN_LOOP_ESCALATION` | 반복 OpenLoop (2+회 = warning, 3+ = critical) + 노후 (7+일) |
+| `MERGE_RECOMMENDATION` | 열린 merge 거버넌스 후보 + 보존 정책 충돌 감지 |
+| `FOLLOW_UP_TASK` | 노후 검증 요청(3+일), 거버넌스 후보, critical 반복 OpenLoop |
+
+### 유효성 분석
+
+**문제점**:
+1. **새 정보 없음**: freshness, governance, maintenance 시그널을 재집계하는 간접 레이어. 각 서비스 API로 직접 접근 가능한 정보만 다시 포장.
+2. **비효율적 조회**: `get_recommendation(id)`이 전체 목록(limit=200)을 재계산 후 선형 스캔.
+3. **로직 중복**: `_stale_decision_recommendations()`가 freshness 평가 로직을 재구현.
+4. **모델 위치**: `RecommendationView`가 `models/retention.py`에 혼입 (구조적 냄새).
+5. **테스트 없음**.
+
+**보류 사유**: MCP "what should I do?" 엔드포인트 같은 명확한 소비자가 생길 때까지 부가가치 없음.
+
+---
+
+## 5. Retention Policies (보존 정책) — KEEP
+
+**파일**: `engram/retention/service.py` (122줄), `engram/models/retention.py` (92줄)
+**테스트**: `tests/test_retention/test_retention_service.py` (2/2 통과)
+
+### 기능
+
+대상별(entity/fact/decision/note/session) 보존 정책을 관리한다.
+
+| 정책 타입 | 효과 |
+|----------|------|
+| `PIN` | 감쇠/삭제 대상에서 영구 제외 |
+| `TTL` | 지정 시점 이후 만료 |
+| `ARCHIVE_ONLY` | 기본 검색에서 숨김 (명시적 조회만 가능) |
+| `NEVER_SUMMARIZE` | 압축/요약 대상에서 제외 (원문 보존) |
+
+### 유효성 분석
+
+**필요한 이유**: 감쇠와 압축을 수행하는 메모리 시스템에서 "이것만은 절대 잊지 마라" (PIN), "검색에서 숨기되 삭제하지 마라" (ARCHIVE_ONLY), "요약으로 뭉개지 마라" (NEVER_SUMMARIZE)는 자연스러운 요구사항이다.
+
+**설계 품질**: 매우 깔끔. 얇고 타입 안전한 래퍼. `is_pinned()`, `is_archive_only()`, `get_ttl()` 같은 편의 메서드가 engine 전체에서 참조됨. 검색 결과 필터링(`_apply_retention_to_search_result`), 브리프 필터링에 깊이 통합됨.
+
+---
+
+## 6. Scoped Memory (스코프 메모리) — KEEP
+
+**파일**: `engram/scopes/service.py` (77줄), `engram/models/scope.py` (41줄)
+**테스트**: `tests/test_scopes/test_service.py` (2/2 통과)
+
+### 기능
+
+계층적 네임스페이스로 메모리를 분리한다.
+
+```
+global
+└── workspace: "company-a"
+    ├── project: "engram"
+    │   ├── channel: "dev-chat"
+    │   └── task: "migration-v11"
+    └── project: "other-project"
+        └── agent: "reviewer-bot"
+```
+
+- `create(name, kind, parent_id)` — 경로 자동 구축, "/" 금지 (경로 주입 방지)
+- `resolve_selection(ScopeSelection)` → `ResolvedScope` (허용 scope ID 목록)
+  - `include_ancestors`: 상위 스코프 팩트 상속
+  - `include_global`: 전역 팩트 포함
+  - `fallback_scope_ids`: 대체 스코프
+
+### 유효성 분석
+
+**필요한 이유**: 멀티 프로젝트/멀티 에이전트 환경에서 "project-alpha의 팩트가 project-beta 검색에 나오면 안 된다"는 기본 요구사항. 계층 구조(workspace > project > channel > task)는 개발 작업 조직 방식에 자연스럽게 매핑.
+
+**설계 품질**: 최소주의적이고 잘 설계됨. 77줄 서비스 + 41줄 모델. `ScopeSelection` → `ResolvedScope` 패턴으로 호출자가 원하는 것을 선언하면 서비스가 해소. store, search, sessions에 모두 `scope_id` 통합.
+