memento-mcp-server 0.1.0

package/docs/ko/Memento-Goals.md

@@ -0,0 +1,217 @@
+# Memento Goals
+
+## 1. 목표 정리
+
+**목표**: 에이전트가 대화/작업 맥락을 잃지 않도록, 사람의 기억 체계(작업기억·일화기억·의미기억·절차기억)를 모사한 스토리지+검색+요약+망각 메커니즘을 제공.
+
+**비목표**: 초대규모 RAG 플랫폼, 범용 데이터레이크. 초기엔 개인/워크스페이스 단위의 장기 기억과 대화-세션 간 전이에 집중.
+
+### 사람의 기억 모델에 대한 근거
+
+- **일화(episodic)/의미(semantic) 분리**: Tulving 계보 – 일화는 사건, 의미는 지식. 두 체계는 상호의존적. [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+
+- **작업기억(working memory)**: 중앙집행·음운고리·시공간 메모리 구성으로 "현재 처리 중인 정보"를 관리. [Simply Psychology](https://www.simplypsychology.org/working-memory.html) +1
+
+- **망각/간격반복**: 에빙하우스 곡선과 "주기적 리마인드"가 장기 유지에 유리. [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+
+### MCP 적용 근거
+
+MCP는 Tools/Resources/Prompts를 표준으로 노출하고, 클라이언트(Claude, ChatGPT, Cursor 등)에서 쉽게 연결 가능. [WorkOS](https://workos.com/) +3, [Model Context Protocol](https://modelcontextprotocol.io/) +3
+
+## 2. 시스템 개요(컴포넌트)
+
+### Memory MCP Server
+
+- **프로토콜**: MCP(spec 2025-03-26)
+- **인터페이스**: tools(기억 쓰기·검색·고정·삭제 등), resources(읽기 전용 뷰), prompts(컨텍스트 주입 템플릿). [Model Context Protocol](https://modelcontextprotocol.io/) +1
+
+### 스토리지
+
+- **기본**: PostgreSQL + pgvector(벡터/메타/트랜잭션 같이 관리). [GitHub](https://github.com/pgvector/pgvector) +1
+- **대안**: SQLite+FTS5(+lancedb)로 임베디드, 또는 Qdrant/Milvus로 분리
+
+### 임베딩 & 요약
+
+텍스트 임베딩 모델(문장 임베딩), "정보 압축 요약기(map-reduce)" 파이프라인.
+
+### 스케줄러/워커
+
+"수면 통합" 배치(야간 클러스터링·요약·규칙 추출), "망각/리뷰" 배치(재노출·삭제 후보 선정).
+
+## 3. 데이터 모델(사람 기억에 대응)
+
+### 핵심 테이블
+
+#### memory_item
+- `id`, `type`(working|episodic|semantic|procedural), `title`, `content`, `source`(chat|tool|file|url), `agent_id`, `user_id`, `project_id`
+- `created_at`, `last_accessed_at`, `importance`(0~1), `pinned`(bool), `privacy_scope`(private|team|public), `origin_trace`(json)
+
+#### memory_embedding
+- `memory_id` FK, `embedding` vector, `dim`
+
+#### memory_tag (N:N)
+- 태그(예: tech:mariadb, pref:coffee, task:ads-settlement)
+
+#### memory_link
+- 기억 간 관계(cause_of, derived_from, duplicates, contradicts) – 의미적 연결망
+
+#### feedback_event
+- `memory_id`, `event`(used|edited|neglected|helpful|not_helpful), `score`, `ts`
+
+### 작업기억(working) 버퍼
+
+#### wm_buffer
+- `session_id`, `items`(json), `token_budget`, `expires_at`
+
+세션 종료/토큰 한도 초과 시 **일화(episodic)**으로 스냅샷 전환.
+
+## 4. 검색·랭킹·망각(수식 포함)
+
+### 4.1 검색 스코어
+
+최종 점수 S:
+
+```
+S = α * relevance + β * recency + γ * importance + δ * usage - ε * duplication_penalty
+```
+
+- **relevance**: 코사인 유사도(임베딩) + keyword TF-IDF 보정
+- **recency**: `exp(-λ * age_days)` (에빙하우스 계열 망각 함수를 응용; λ는 도메인별 튜닝) [PMC](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2657600/) +1
+- **importance**: 명시/추론("사용자 선호·규칙·장기목표"는 가중치↑)
+- **usage**: 조회·인용·재사용 빈도 로그 스케일
+- **duplication_penalty**: 군집 내 유사 항목 중복 감점
+
+### 4.2 망각·간격반복
+
+- **소프트 삭제 후보 큐**: S가 낮고 `last_accessed_at` 오래된 항목 중 비핀(pinned)·비정책 항목
+- **리텐션 정책**: 태그/스코프별 TTL(예: wm: 48시간, episodic: 90일, semantic: 무기한)
+- **간격반복**: 중요도 상위 항목은 리뷰 이벤트(카드 형태 리마인드)를 생성해 재노출
+
+### 4.3 의미 통합("수면 통합")
+
+최근 episodic을 군집화→ 충돌/일관성 검사→ 규칙·사실 형태의 semantic 생성
+
+CLS 가설(해마-네오코텍스 보완 학습)을 모티프로 "빠른 일화→느린 의미 통합"을 구현. [PubMed](https://pubmed.ncbi.nlm.nih.gov/) +1
+
+## 5. MCP 인터페이스 설계(도구/리소스/프롬프트)
+
+### 5.1 tools (요약된 시그니처)
+
+#### remember
+- **입력**: `content`, `type?`, `tags?`, `importance?`, `source?`, `privacy_scope?`
+- **출력**: `memory_id`
+
+#### recall
+- **입력**: `query`, `filters?`(type/tags/time/project/agent), `limit?`
+- **출력**: `items[]`(snippet, score, recall_reason)
+
+#### pin / unpin
+
+#### forget
+- 하드/소프트 삭제 옵션, GDPR식 "지우기 권리" 지원
+
+#### summarize_thread
+- 현재 세션 로그→ wm_buffer 요약→ episodic 저장
+
+#### link
+- 기억 간 관계 생성(원인·파생·중복·모순)
+
+#### export
+- NDJSON/Markdown/CSV 내보내기
+
+#### feedback
+- 사용성/정확성 피드백 수집(helpful, not_helpful, 정답 첨부)
+
+**MCP 스펙 근거**: 툴/리소스/프롬프트를 표준화해 클라이언트가 자동 발견·호출·구성. [Model Context Protocol](https://modelcontextprotocol.io/) +1
+
+### 5.2 resources
+
+- `memory/{id}`: 읽기 전용 단일 뷰
+- `memory/search?query=...`: 최근 검색 결과 캐시 리소스(클라이언트 사이드 프리뷰에 유용)
+
+### 5.3 prompts
+
+#### memory_injection
+- **설명**: "이번 턴 답변 전에 '상위 5개 관련 기억 요약'을 컨텍스트로 주입"
+- **파라미터**: `query`, `token_budget`
+
+MCP Prompts 기능으로 에이전트가 쉽게 가져다 씀. [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## 6. 에이전트 실행 플로우
+
+1. **WM 적재**: 현재 사용자 메시지 + 직전 n턴 요약을 `wm_buffer`에 정리
+2. **질의 구성**: `query = user_msg + task + wm_summary`
+3. **recall 호출**:
+   - 필터: `project_id`, `tags`, `type in {semantic, episodic}`
+   - 1차 ANN(벡터) → 2차 rerank(BM25/keyword + rule match)
+   - 중복 제거 & 압축: map-reduce 요약, 충돌은 `link(contradicts)`로 기록
+4. **프롬프트 주입**: `prompts.memory_injection`으로 상위 K개를 투입
+5. **답변 생성 후**:
+   - `remember`로 새로운 사실/선호/결정 기록
+   - `feedback(helpful)` 신호 반영
+6. **배치 작업(야간)**: 군집화·요약 통합·망각/리마인드 스케줄링
+
+## 7. 최소기능(MVP) 스펙
+
+- 기억 쓰기/읽기/검색/핀/삭제 툴
+- 일화/의미 두 타입만 우선 지원(작업기억은 세션 캐시로)
+- **스코어**: `S = 0.5*relevance + 0.2*recency + 0.2*importance + 0.1*usage`
+- **리텐션**: episodic 90d, semantic 무기한, wm 48h
+- **저장소**: Postgres+pgvector, ivfflat 인덱스, cosine 거리. [GitHub](https://github.com/pgvector/pgvector) +1
+- MCP `prompts.memory_injection` 1종
+
+## 8. 예시: TypeScript MCP 서버 스켈레톤
+
+```typescript
+// package: mcp-memory-server
+import { Server } from "@modelcontextprotocol/sdk/server";
+import { z } from "zod";
+import { recall, remember, pin, unpin, forget, summarizeThread, link, exportMem, feedback } from "./tools";
+
+const server = new Server({ name: "mcp-memory", version: "0.1.0" });
+
+// Tools
+server.tool("remember", {
+  schema: z.object({
+    content: z.string(),
+    type: z.enum(["episodic","semantic"]).default("episodic"),
+    tags: z.array(z.string()).optional(),
+    importance: z.number().min(0).max(1).default(0.5),
+    source: z.string().optional(),
+    privacy_scope: z.enum(["private","team","public"]).default("private")
+  }),
+  handler: remember
+});
+
+server.tool("recall", {
+  schema: z.object({
+    query: z.string(),
+    filters: z.object({
+      type: z.array(z.enum(["episodic","semantic"])).optional(),
+      tags: z.array(z.string()).optional(),
+      project_id: z.string().optional(),
+      time_from: z.string().optional(),
+      time_to: z.string().optional()
+    }).optional(),
+    limit: z.number().default(8)
+  }),
+  handler: recall
+});
+
+// ... pin/unpin/forget/summarizeThread/link/export/feedback 등록 ...
+
+// Resources
+server.resource("memory/{id}", async (params) => {/* read-only view */});
+
+// Prompts
+server.prompt("memory_injection", {
+  params: [{ name: "query", required: true }, { name: "token_budget", required: false }],
+  getPrompt: async ({ query, token_budget = 1200 }) => {
+    const items = await recall({ query, limit: 6 });
+    const summary = await compress(items, token_budget);
+    return [{ role: "system", content: `관련 장기기억 요약:\n${summary}` }];
+  }
+});
+
+server.start();
+```

package/docs/ko/Memento-M1-DetailSpecs.md

@@ -0,0 +1,130 @@
+# MCP Memory Server M1 상세 설계 문서
+
+## 1. 목적
+
+본 단계(M1)는 개인 사용자가 로컬 환경에서 가볍게 실행할 수 있는 기억 보조 MCP 서버를 구현하는 것을 목표로 한다.
+데이터베이스는 별도의 설치 없이 사용할 수 있는 SQLite 임베디드 DB를 사용하며, MCP 인터페이스를 통해 기억 저장, 검색, 삭제, 고정 등의 기본 기능을 제공한다.
+
+## 2. 전체 아키텍처
+
+- **클라이언트**: MCP를 지원하는 IDE(예: Cursor) 또는 AI Agent
+- **서버**: MCP Memory Server (Node.js/TypeScript 기반)
+- **스토리지**: SQLite 데이터베이스(memory.db 파일)
+
+**구조**:
+```
+[Client/Agent] ↔ [MCP Memory Server] ↔ [SQLite DB (memory.db)]
+```
+
+## 3. 기능 범위
+
+### 기억 저장 (remember)
+- **입력**: content, type, tags, importance, privacy_scope
+- **출력**: memory_id
+- **동작**: 텍스트를 DB에 저장하고, 임베딩 생성 후 벡터 컬럼에 기록
+
+### 기억 검색 (recall)
+- **입력**: query, filters(type, tags, date), limit
+- **출력**: 관련 기억 목록
+- **동작**: FTS5(키워드) + VSS(벡터 검색) 결합
+
+### 기억 삭제 (forget)
+- **소프트 삭제**: TTL 만료 시 자동 제거
+- **하드 삭제**: 사용자가 직접 호출
+
+### 기억 고정/해제 (pin/unpin)
+- 특정 기억을 TTL, 망각 정책에서 제외
+
+## 4. 데이터베이스 설계 (SQLite)
+
+### 4.1 메인 테이블
+
+```sql
+CREATE TABLE memory_item (
+  id TEXT PRIMARY KEY,
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT,
+  importance REAL,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  last_accessed TIMESTAMP,
+  pinned BOOLEAN DEFAULT FALSE
+);
+```
+
+### 4.2 인덱스
+
+#### FTS5 (텍스트 검색)
+```sql
+CREATE VIRTUAL TABLE memory_item_fts USING fts5(content);
+```
+
+#### VSS (벡터 검색, 1536차원 예시)
+```sql
+CREATE VIRTUAL TABLE memory_item_vss USING vss0(embedding(1536));
+```
+
+## 5. MCP 인터페이스 (M1 한정)
+
+### Tools
+- `remember(content, type?, tags?, importance?, privacy_scope?)`
+- `recall(query, filters?, limit?)`
+- `forget(id, hard?)`
+- `pin(id)` / `unpin(id)`
+
+### Resources
+- `memory/{id}` (단일 기억 읽기)
+
+### Prompts
+- `memory_injection(query, token_budget)`
+  - 상위 5개 관련 기억을 요약하여 프롬프트에 주입
+
+## 6. 망각 정책
+
+- **작업기억 (working)**: 48시간 유지 후 삭제
+- **일화기억 (episodic)**: 90일 유지
+- **의미기억 (semantic)**: 무기한
+- **고정(pin)**: 삭제 대상에서 제외
+
+주기적으로 실행되는 배치 작업(cron job)으로 만료된 레코드 정리.
+
+## 7. 동작 흐름
+
+### 기억 저장
+1. 사용자가 `remember` 호출
+2. DB에 기록 → FTS5 인덱스 업데이트 → 임베딩 생성 후 VSS 테이블 기록
+
+### 기억 검색
+1. 사용자가 `recall` 호출
+2. FTS5로 키워드 검색 → VSS로 벡터 검색 → 점수 합산 → 상위 K개 반환
+
+### 망각/삭제
+1. 배치 작업으로 TTL 만료 항목 삭제
+2. 사용자가 `forget` 호출 시 즉시 제거
+
+## 8. 운영 및 배포
+
+- **실행 환경**: Node.js (v20 이상)
+- **배포 방법**: 로컬 실행
+  ```bash
+  node memory-server.js
+  ```
+- **DB 관리**: 단일 memory.db 파일 (로컬 저장소에 보관)
+- **백업/복원**: 파일 복사로 처리 가능
+
+## 9. 한계와 다음 단계 고려
+
+**한계**: 단일 사용자 전용, 권한 관리 없음
+
+**확장 고려**:
+- M2에서 API Key 인증 추가
+- SQLite 서버 모드 전환
+- 팀 협업 가능하도록 ACL(user_id, privacy_scope) 활용 예정
+
+## 10. 체크리스트
+
+- [ ] SQLite DB 초기 스키마 생성 완료
+- [ ] MCP Tools (remember, recall, forget, pin/unpin) 구현 완료
+- [ ] FTS5 + VSS 기반 검색 정상 동작
+- [ ] TTL 기반 망각 정책 배치 스크립트 적용
+- [ ] 로컬 환경에서 MCP Client와 연동 테스트 완료

package/docs/ko/Memento-Milestones.md

@@ -0,0 +1,134 @@
+# 📄 MCP Memory Server 설계 및 마일스톤 문서
+## 🎯 비전
+
+사람의 기억 구조(작업기억·일화기억·의미기억)를 모방한 AI Agent 기억 보조 MCP 서버를 구현한다.
+
+- 개인(MVP): 단일 SQLite 파일 기반, 로컬에서 가볍게 실행
+- 팀: 내부망 전용 서버 + 단일 API Key, SQLite + 직렬화 큐
+- 조직: Postgres + pgvector + JWT 인증, SSO/LDAP 연동
+
+## 🛠 마일스톤 개요
+
+| 단계 | 대상 | 스토리지 | 인증 | 보안 범위 | 운영 방식 |
+|------|------|----------|------|-----------|-----------|
+| M1 | 개인 | SQLite 임베디드 | 없음 | 로컬 | 로컬 실행 |
+| M2 | 팀 | SQLite 서버 모드 (WAL + 직렬화 큐) | 단일 API Key | 내부망 전용 | Docker 단일 컨테이너 |
+| M3 | 조직 초입 | Postgres + pgvector | JWT (사용자별 토큰) | 내부망 or VPN | Docker Compose (서버+DB) |
+| M4 | 조직 확장 | Postgres + HA 구성 | JWT + RBAC + SSO/LDAP | 기업 보안 정책 준수 | Kubernetes/클라우드 RDS |
+## ⚙️ 단계별 설계
+
+### 🔹 M1. 개인용 (MVP)
+
+- **DB**: SQLite (memory.db)
+- **인덱스**: FTS5, sqlite-vec (벡터 검색)
+- **MCP Tools**: remember, recall, forget, pin
+- **망각 정책**: TTL 기반 (working 48h, episodic 90d, semantic 무기한)
+- **운영**: 로컬 실행 (node memory-server.js)
+
+### 🔹 M2. 팀 협업 (내부망 전용 서버)
+
+- **DB**: SQLite (WAL 모드)
+- **쓰기 처리**: 서버 레벨 큐잉 → 직렬화
+- **읽기 처리**: 다중 동시 읽기 가능
+- **인증**: 단일 API Key (API_KEY=team-secret-key)
+- **보안**: 내부망 전용 (외부 포트 차단)
+- **운영**: Docker 단일 컨테이너
+
+```yaml
+services:
+  memory-server:
+    build: .
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - DB_PATH=/app/data/memory.db
+      - API_KEY=team-secret-key
+```
+
+- **ACL**: privacy_scope (private | team) 적용
+
+### 🔹 M3. 조직 초입 (Postgres 전환)
+
+- **DB**: Postgres 15+, pgvector 확장
+
+**스키마**:
+
+```sql
+CREATE TABLE memory_item (
+  id UUID PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  project_id TEXT,
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT,
+  importance REAL,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMPTZ DEFAULT now(),
+  last_accessed TIMESTAMPTZ,
+  embedding vector(1536),
+  content_tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
+);
+CREATE INDEX ON memory_item USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+CREATE INDEX ON memory_item USING GIN (content_tsv);
+```
+
+- **인증**: JWT 기반 사용자별 토큰 (user_id claim 포함)
+- **보안**: 내부망 or VPN 제한
+- **운영**: Docker Compose (Memory Server + Postgres)
+
+### 🔹 M4. 조직 확장 (고가용성 + 기업 보안)
+
+- **DB**: Postgres 클러스터 (HA 구성, 클라우드 RDS 가능)
+- **인증**: JWT + RBAC + SSO/LDAP 연동
+- **권한 모델**:
+  - privacy_scope: private/team/public
+  - project_id: 워크스페이스 단위
+  - RBAC(Role-Based Access Control) → 관리자/편집자/조회자
+- **운영**: Kubernetes, Helm Chart 배포, 모니터링(Prometheus)
+- **추가 기능**: 자동 아카이빙, 백업/복원, GDPR-style 삭제
+
+## 📦 MCP 인터페이스 (공통)
+
+### Tools
+
+- `remember(content, type, tags?, importance?, privacy_scope?)`
+- `recall(query, filters?, limit?)`
+- `pin(id), unpin(id)`
+- `forget(id, hard?)`
+- `summarize_thread(session_id)`
+- `link(src, dst, rel)`
+- `export(format)`
+- `feedback(memory_id, helpful?)`
+
+### Resources
+
+- `memory/{id}`
+- `memory/search?query=...`
+
+### Prompts
+
+- `memory_injection(query, token_budget)` → 상위 K개 관련 기억 요약 주입
+
+## 🔐 보안 모델 정리
+
+- **M1**: 없음 (로컬 전용)
+- **M2**: 단일 API Key (팀 공유)
+- **M3**: JWT (사용자별 토큰, 조직 계정 서버 연동 가능)
+- **M4**: JWT + RBAC + SSO/LDAP → 기업 보안 정책 준수
+
+## 📑 마이그레이션 가이드 요약
+
+1. SQLite에서 memory_item.csv 추출
+2. Postgres에 스키마 생성 (pgvector, tsvector)
+3. CSV import → `\copy`
+4. embedding은 재계산 후 업데이트
+5. MCP Memory Server의 DB 드라이버만 교체
+
+## ✅ 체크리스트
+
+- [ ] 개인용 SQLite 서버 완성
+- [ ] 팀 단계 Docker 배포 + API Key 적용
+- [ ] Postgres 마이그레이션 문서 완성
+- [ ] 조직 단계 JWT 인증 연동
+- [ ] SSO/LDAP 붙이는 로드맵 확정

package/docs/ko/Search-Ranking-Memory-Decay-Formulas.md

@@ -0,0 +1,177 @@
+# 검색 랭킹 및 망각을 위한 수식
+
+## 1) 최종 랭킹 점수
+
+$$S = \alpha \cdot \text{relevance} + \beta \cdot \text{recency} + \gamma \cdot \text{importance} + \delta \cdot \text{usage} - \varepsilon \cdot \text{duplication\_penalty}$$
+
+**기본 계수(M1 추천)**: $\alpha=0.50$, $\beta=0.20$, $\gamma=0.20$, $\delta=0.10$, $\varepsilon=0.15$
+
+**의미**: 후보 m에 대해 관련성(relevance)과 최근성(recency), 중요도(importance), 사용성(usage)을 올리고, 중복(duplication_penalty)을 깎는다.
+
+**실무 팁**: 처음엔 위 기본값으로 시작 → A/B 테스트로 $\alpha$, $\beta$를 조정하고, 결과 다양성이 부족하면 $\varepsilon$를 키운다.
+
+## 2) 관련성(relevance) 구성
+
+$$\text{relevance} = w_e \cdot \text{sim}_e + w_k \cdot \text{bm25\_norm} + w_t \cdot \text{tag\_match} + w_p \cdot \text{title\_hit}$$
+
+**기본 가중치(M1)**: $w_e=0.60$, $w_k=0.30$, $w_t=0.05$, $w_p=0.05$
+
+### (1) 임베딩 유사도(코사인)
+
+$$\text{sim}_e = \max(0, \cos(\mathbf{E}(q), \mathbf{E}(m)))$$
+
+$\mathbf{E}(x)$는 임베딩 함수. 코사인 값이 음수가 나오는 모델이라면 0으로 클램프해 점수 음수화를 방지.
+
+### (2) 키워드(BM25의 정규화)
+
+$$\text{bm25\_norm} = \frac{\text{BM25}}{\text{BM25} + k_{\text{norm}}}$$
+
+권장 $k_{\text{norm}}=2.0$. 어떤 쿼리든 [0,1]로 매핑해 다른 피처와 합치기 쉽다.
+
+### (3) 태그 매칭(자카드 유사도)
+
+$$\text{tag\_match} = \frac{|T_q \cap T_m|}{|T_q \cup T_m|}$$
+
+쿼리 태그($T_q$)와 문서 태그($T_m$) 겹침 정도. 태그를 적극 쓰면 검색 품질이 눈에 띄게 오른다.
+
+### (4) 타이틀 매치(정확·접두·N-gram 가산)
+
+$$\text{title\_hit} = I_{\text{exact}} \cdot 1.0 + I_{\text{prefix}} \cdot 0.5 + I_{\text{ngram}} \cdot 0.2$$
+
+$I_*$는 해당 조건 충족 시 1, 아니면 0. 세밀한 튜닝 구간.
+
+### 후보 생성 팁(2단계 검색 권장)
+
+1차(ANN): 임베딩 상위 $N_e$개, 2차(BM25): 키워드 상위 $N_k$개 → 합집합을 후보 세트로 만들고 위 relevance로 재랭킹.
+
+## 3) 최근성(recency) = 반감기 기반 지수 감쇠
+
+$$\text{recency} = \exp\left(-\frac{\ln(2) \cdot \text{age\_days}}{\text{half\_life}(\text{type})}\right)$$
+
+- $\text{half\_life}(\text{working})=2$
+- $\text{half\_life}(\text{episodic})=30$ 
+- $\text{half\_life}(\text{semantic})=180$ (단위: 일)
+
+**의미**: 각 타입별 기억의 반감기를 다르게 둬서, 작업기억은 빠르게 색이 바래고 의미기억은 오래 간다.
+
+**튜닝**: 도메인이 빠르면(예: 이슈 대응 노트) half_life를 더 짧게, 지식 베이스는 더 길게.
+
+## 4) 중요도(importance) = 사용자 가중 + 시스템 가중
+
+$$\text{importance} = \text{clamp}(\text{imp\_user} + 0.20 \cdot \text{pinned} + \text{type\_boost}, 0, 1)$$
+
+- $\text{imp\_user} \in [0,1]$: 사용자가 저장 시 준 중요도(기본 0.5)
+- $\text{pinned} \in \{0,1\}$: 고정 시 1 (망각·감쇠에서 보호)
+- $\text{type\_boost}$: semantic=+0.10, episodic=0.00, working=−0.05 (예시)
+- $\text{clamp}(a,0,1)$: 0~1 범위로 자르기
+
+**팁**: imp_user를 그대로 쓰기보단, 프로젝트별 정책(예: project:정산 +0.05)을 더해도 좋다.
+
+## 5) 사용성(usage) = 로그 스케일 집계의 정규화
+
+$$\text{usage\_raw} = \log(1 + \text{view\_cnt}) + 2 \cdot \log(1 + \text{cite\_cnt}) + 0.5 \cdot \log(1 + \text{edit\_cnt})$$
+
+$$\text{usage} = \frac{\text{usage\_raw} - \text{min\_batch}}{\text{max\_batch} - \text{min\_batch} + \varepsilon}$$
+
+$\text{cite\_cnt}$(재사용/인용) 가중치를 가장 높게. $\varepsilon$는 $1e-6$ 같은 작은 값.
+
+**배치 정규화 이유**: 문서별 절대치 편차를 줄여 쿼리·세션마다 안정적 스케일을 보장.
+
+## 6) 중복 패널티(duplication_penalty) = MMR식 다양성 제어
+
+$$\text{duplication\_penalty} = \max_{j \in R} \text{sim}_e(m, j)$$
+
+$R$: 이미 현재 결과 리스트에 선정된 항목 집합
+
+**해석**: 새 후보 m이 기존 선정 결과와 가장 비슷한 정도를 패널티로 준다.
+
+결과 다양성이 부족하면 $\varepsilon$(최종식의 계수)를 키우거나, 아래의 MMR 후처리를 사용.
+
+### MMR 후처리(선택)
+
+$$\text{MMR}(m) = \lambda \cdot S(m) - (1 - \lambda) \cdot \max_{j \in R} \text{sim}_e(m, j)$$
+
+추천 $\lambda=0.8$. 최종 Top-K를 뽑을 때, S 점수에 다양성 항을 더 얹는 방식.
+
+## 7) 망각(garbage collection)·리마인드(spaced review)
+
+망각은 "삭제"만이 아니라 "재노출(복습)"도 포함한다. 점수 기반의 삭제 위험도와 리뷰 스케줄을 함께 쓰는 게 가장 안정적이다.
+
+### 7.1 삭제 위험도(ForgetScore)
+
+$$\text{ForgetScore} = u_1 \cdot (1 - \text{recency}) + u_2 \cdot (1 - \text{usage}) + u_3 \cdot \text{dup\_ratio} - u_4 \cdot \text{importance} - u_5 \cdot \text{pinned}$$
+
+**기본 계수(M1)**: $u_1=0.35$, $u_2=0.25$, $u_3=0.20$, $u_4=0.15$, $u_5=0.30$
+
+$\text{dup\_ratio}$: 군집 내 유사 항목 비중(없으면 duplication_penalty를 0~1로 정규화해 대체)
+
+**해석**: 오래되고($1-\text{recency}↑$), 안 쓰이고($1-\text{usage}↑$), 중복 많을수록($\text{dup\_ratio}↑$) 지우기 쉽다. 중요하거나 핀인 항목은 보호.
+
+### 삭제 정책(예시)
+
+- **소프트 삭제 후보**: $\text{ForgetScore} \geq \theta_{\text{soft}}$ AND $\text{age\_days} \geq \text{TTL}_{\text{soft}}(\text{type})$
+- **하드 삭제**: $\text{ForgetScore} \geq \theta_{\text{hard}}$ AND $\text{age\_days} \geq \text{TTL}_{\text{hard}}(\text{type})$
+
+**권장값(M1)**:
+- $\theta_{\text{soft}}=0.6$, $\theta_{\text{hard}}=0.8$
+- $\text{TTL}_{\text{soft}}(\text{working})=2$, $\text{TTL}_{\text{soft}}(\text{episodic})=30$, $\text{TTL}_{\text{soft}}(\text{semantic})=\infty$
+- $\text{TTL}_{\text{hard}}(\text{working})=7$, $\text{TTL}_{\text{hard}}(\text{episodic})=180$, $\text{TTL}_{\text{hard}}(\text{semantic})=\infty$
+
+### 7.2 간격 반복(Spaced Review) 스케줄
+
+$$p_{\text{recall}}(t) = \exp\left(-\frac{t}{\tau}\right)$$
+
+$$\tau_{\text{next}} = \tau_{\text{prev}} \cdot (1 + a_1 \cdot \text{importance} + a_2 \cdot \text{usage} + a_3 \cdot \text{feedback\_helpful} - a_4 \cdot \text{feedback\_bad})$$
+
+**추천 계수**: $a_1=0.6$, $a_2=0.4$, $a_3=0.5$, $a_4=0.7$
+
+**의미**: 중요하고 자주 쓰이고, 유용하다고 표시된 기억은 **기억 반감기($\tau$)**가 늘어나서 리뷰 주기가 길어진다.
+
+**스케줄링 조건(예시)**: $p_{\text{recall}}(t) \leq 0.7$가 되는 시점을 다음 리뷰 시점으로 잡아 리마인드 카드 발행.
+
+### 간단 프리셋(복잡한 SM-2 대신 라이트 버전)
+
+첫 저장 후 1일, 6일, 그 다음부터는 $\text{interval\_next} = \lceil \text{interval\_prev} \cdot (1 + 0.5 \cdot \text{importance} + 0.3 \cdot \text{usage}) \rceil$
+
+## 8) 후보 생성, 재랭킹, 다양화 파이프라인(권장)
+
+### CandidateGen
+$$C = \text{TopN}_e(\text{ANN by sim}_e) \cup \text{TopN}_k(\text{BM25})$$
+(권장 $N_e=50$, $N_k=50$)
+
+### Feature Compute
+각 $m \in C$에 대해 relevance, recency, importance, usage, duplication_penalty 계산
+
+### Primary Score
+$$S(m) = \alpha \cdot \text{relevance} + \beta \cdot \text{recency} + \gamma \cdot \text{importance} + \delta \cdot \text{usage} - \varepsilon \cdot \text{duplication\_penalty}$$
+
+### Diversification (선택)
+Greedy로 MMR 적용해 Top-K 생성
+
+### Thresholding
+$S(m) \geq \theta_{\text{keep}}$만 유지 (예: $\theta_{\text{keep}}=0.35$)
+
+## 9) 정규화와 캘리브레이션
+
+모든 부분 점수는 [0,1] 스케일을 유지하면 조합이 쉽다. 배치마다 분산이 큰 피처는 배치 정규화를 권장.
+
+$$x_{\text{norm}} = \frac{x - \text{min\_batch}}{\text{max\_batch} - \text{min\_batch} + \varepsilon}$$
+
+예: usage, duplication_penalty, bm25_norm에 적용
+
+**장점**: 쿼리 편향, 컬렉션 편차를 줄여 점수 안정성↑
+
+## 10) M1 기본 파라미터 표(요약)
+
+| 항목 | 값 |
+|------|-----|
+| **최종식** | $\alpha=0.50$, $\beta=0.20$, $\gamma=0.20$, $\delta=0.10$, $\varepsilon=0.15$ |
+| **relevance 가중** | $w_e=0.60$, $w_k=0.30$, $w_t=0.05$, $w_p=0.05$ |
+| **recency** | $\text{half\_life}(\text{working})=2$, $\text{episodic}=30$, $\text{semantic}=180$ |
+| **importance** | $\text{pinned}=+0.20$, $\text{type\_boost}(\text{semantic}=+0.10, \text{working}=-0.05)$ |
+| **usage** | log 기반, 배치 정규화 |
+| **duplication_penalty** | max sim to selected |
+| **망각** | $\theta_{\text{soft}}=0.6$, $\theta_{\text{hard}}=0.8$, TTL_soft/hard 위 표 참조 |
+| **리뷰** | $p_{\text{recall}}(t)=\exp(-t/\tau)$, 첫 1일→6일→가변 배수 |
+
+이대로 구현하면 **M1(개인용)**에서 바로 쓸 수 있고, M2/M3로 갈 때는 계수만 재튜닝하면 된다.