memento-mcp-server 1.6.0 → 1.7.1

package/docs/ko/Memento-Goals.md

@@ -1,217 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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

@@ -1,134 +0,0 @@
-# 📄 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

@@ -1,177 +0,0 @@
-# 검색 랭킹 및 망각을 위한 수식
-
-## 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로 갈 때는 계수만 재튜닝하면 된다.