Engram

모든 생각은 흔적을 남깁니다.

AI 에이전트에게 망각할 줄 아는 뇌를 선물하세요.

Engram은 완전히 로컬에서 실행되는 MCP 메모리 서비스입니다. 단순히 데이터를 '저장하고 불러오는' 것을 넘어, 인간의 기억이 가진 망각, 강화, 연상 메커니즘을 시뮬레이션하여 에이전트가 세션을 넘나들며 정말 중요한 것은 기억하고, 더 이상 필요 없는 세부 사항은 자연스럽게 잊도록 합니다.

클라우드 의존성 제로, 데이터는 항상 당신의 기기에 머뭅니다.

해결하는 문제

문제 1: 세션 간 상태 단절

AI 에이전트와의 모든 대화는 백지상태에서 시작됩니다. 어제 알려준 선호도, 지난주에 내린 아키텍처 결정, 지난달에 겪었던 시행착오 등 모든 것이 다음 대화에서는 초기화됩니다. 컨텍스트 윈도우가 비워지는 것은 곧 뇌가 포맷되는 것과 같습니다.

문제 2: 파일 엔트로피 증가

CLAUDE.md나 .cursorrules에 컨텍스트를 쑤셔 넣는 것은 문제를 해결하는 것처럼 보이지만, 실제로는 더 큰 문제를 만듭니다. 파일은 점점 길어지고, 오래된 정보와 새로운 정보가 뒤섞이며, 수동 관리 비용은 계속 증가합니다. 당신은 기억을 관리하는 것이 아니라, 점점 읽기 힘들어지는 문서를 유지보수하고 있는 것입니다.

문제 3: 엔지니어링 상태 손실

에이전트가 무엇을 했는지, 어디서 막혔는지, 다음에 무엇을 해야 하는지 등 구조화된 엔지니어링 상태를 저장할 곳이 없습니다. 매번 새로운 세션마다 10분씩 '재정렬'을 하고 똑같은 일을 반복해야 합니다.

Engram의 해결책: '모든 것을 저장'하는 것이 아니라, 인간의 기억이 가진 망각-강화-연상 메커니즘을 시뮬레이션합니다:

• 중요한 선호도와 결정은 감쇠 속도가 매우 느려 거의 영구적으로 보존됩니다.

• 임시 디버깅 컨텍스트는 11일이 지나면 자연스럽게 사라집니다.

• 반복적으로 회상되는 지식은 사용할수록 더 견고해집니다.

• 모순되는 정보는 자동으로 덮어쓰여져 혼란을 방지합니다.

• v0.2 추가: 구조화된 세션 핸드오프(session handoff)를 통해 다음 세션이 처음부터가 아닌 중단 지점부터 이어질 수 있습니다.

• v0.4 추가: 엔지니어링 상태 허브 — 구조화된 실패 원인 분석(track_failure) 및 진행 상황 추적(track_progress)을 통해 에이전트가 정보뿐만 아니라 엔지니어링 상태까지 기억하게 합니다.

Related MCP server: Ori Mnemos

핵심 메커니즘

1. 에빙하우스 망각 곡선

모든 기억은 강도(strength) 값을 가지며, 시간에 따라 지수 곡선으로 감쇠합니다:

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

세 가지 요소가 기억의 수명을 결정합니다:

4가지 기억 카테고리:

설계 의도: 성공적인 전략은 가장 오래 기억하고(strategy ~38일), 실패한 교훈은 가장 짧게 기억합니다(failure ~11일). 환경은 변하기 때문에 어제의 문제는 내일이면 해결되었을 수도 있기 때문입니다.

2. 지능형 중복 제거 및 모순 해결

새로운 기억을 저장할 때 단순히 추가하는 것이 아니라, 기존 기억과 의미론적 비교를 먼저 수행합니다:

相似度 ≥ 0.85 → REINFORCE  只增加回忆次数，不重复存储
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE   用新内容覆盖旧内容
  └── 语义兼容 → MERGE     合并为一条更完整的记忆
相似度 < 0.65 → NEW        存为新记忆

모순 탐지는 극성 분석을 통해 구현됩니다: 긍정 단어(prefer/love/adopt)와 부정 단어(avoid/hate/reject), 그리고 부정어(not/don't/never)를 추출하여 두 기억이 상반된 입장을 취하는지 판단합니다.

예: 기존에 '사용자 선호 TypeScript'가 있는데 '사용자 TypeScript 포기하고 Go 사용 결정'이 들어오면, 시스템은 이를 모순으로 인식하여 자동으로 새 기억으로 대체합니다.

3. 하이브리드 검색 (벡터 + BM25 + 그래프)

기억을 불러올 때 3단계 하이브리드 점수 방식을 사용합니다:

最终得分 = 0.4 × BM25关键词得分 + 0.6 × (语义相似度 × 衰减强度) + 图谱加成

왜 벡터 검색만 사용하지 않나요?

3단계 융합 효과: "데이터베이스 성능"으로 검색하면 성능을 직접 언급한 기억뿐만 아니라, 그래프를 통해 연관된 인덱싱 전략, 캐싱 결정 등의 기억까지 찾아낼 수 있습니다.

4. 의미론적 그래프

모든 기억은 저장될 때 기존 기억들과 의미론적 관계를 맺습니다:

• 모든 기존 기억과의 코사인 유사도 계산

• 유사도 ≥ 0.40인 경우 양방향 엣지 생성, 가중치 = 유사도 × 0.5

• 각 기억은 최대 5개의 가장 유사한 이웃과 연결

그래프의 두 가지 핵심 역할:

연상 발견: 검색 시 적중한 기억에서 BFS(최대 깊이 2)를 수행하여, 검색어와 직접적인 의미 유사도가 없더라도 연관된 기억을 찾아냅니다. 인간의 '꼬리에 꼬리를 무는' 연상과 같습니다.

체인 보호: 특정 기억의 강도가 임계값 이하로 떨어져도, 이웃 기억 중에 강한 기억이 있다면 해당 기억을 유지합니다. 두 중요한 지식을 잇는 가교 역할을 할 수 있기 때문입니다.

5. 자동 통합 및 삭제

백그라운드에서 12시간마다 유지보수 작업이 실행됩니다:

통합(Consolidation):

1. 유사도 ≥ 0.70인 기억 클러스터 식별

2. 중요도가 가장 높은 기억을 메인 기억으로 유지

3. 나머지 기억들의 고유 정보를 병합

4. 벡터 및 그래프 관계 재계산

5. 병합된 중복 기억 삭제

삭제(Pruning):

1. 각 기억의 현재 강도 계산

2. 강도 < 0.05 이고 체인 안전 검사 통과 → 삭제

3. 강도 < 0.05이지만 이웃이 강함 → 유지 (체인 보호)

즉, 메모리 저장소는 자동으로 간결하게 유지됩니다. 수동으로 정리할 필요도 없고, 무한히 팽창하지도 않습니다.

엔지니어링 상태 허브 (v0.4)

Engram은 단순한 '정보 저장' 메모리 플러그인이 아니라, 엔지니어링 프로세스를 이해하는 상태 계층입니다.

실패 원인 분석 (track_failure)

에이전트가 버그, 테스트 실패, 배포 문제를 겪을 때 구조화된 형식으로 기록합니다:

# MCP 调用
track_failure(
    error="CSRF token missing on checkout",
    component="payment",
    severity="critical",        # → importance=0.9
    root_cause="middleware not loaded after refactor",
    fix="re-add CsrfMiddleware to pipeline",
    related_test_ids=["test_checkout_01", "test_payment_csrf"]
)

설계 결정:

• severity는 자동으로 importance에 매핑 (critical=0.9, major=0.7, minor=0.5)

• failure 카테고리 고정 (가장 빠른 감쇠 λ=0.35, ~11일 반감기) — 환경은 변하므로 오래된 실패 기록은 자연스럽게 만료됨

• component 필드는 모듈별 통계 집계를 지원하여 고위험 영역을 빠르게 파악

진행 상황 추적 (track_progress)

세션을 넘나들며 기능/작업 상태 추적:

track_progress(
    feature="login-flow-refactor",
    status="in_progress",       # → importance=0.8
    completion=60,
    blockers=["waiting for API design review"],
    quality_score=0.85,
    notes="auth module done, UI pending"
)

설계 결정:

• status는 자동으로 importance에 매핑 (blocked=0.9 최고, done=0.5 최저)

• strategy 카테고리 고정 (가장 느린 감쇠 λ=0.10, ~38일 반감기) — 진행 상태는 가장 오래 기억해야 함

• 완료된 기능은 자연스럽게 감쇠되어 사라지므로 수동 정리 불필요

엔지니어링 지표 (memory_stats 강화)

memory_stats는 이제 엔지니어링 데이터를 자동으로 집계합니다:

{
  "total": 42,
  "categories": {"fact": 20, "failure": 8, "strategy": 14},
  "engineering": {
    "failures": {
      "total": 8,
      "by_component": {"auth": 5, "payment": 3},
      "by_severity": {"critical": 2, "major": 6}
    },
    "features": {
      "total_tracked": 4,
      "active": {
        "login-refactor": {"status": "in_progress", "completion": 60},
        "payment-fix": {"status": "blocked", "completion": 30}
      }
    }
  }
}

기술 아키텍처

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────────────┐
│              server.py                       │
│  8 MCP tools  ·  APScheduler (12h 维护)      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─ 写入路径 ──────┐  ┌─ 读取路径 ──────┐    │
│  │  resolve.py     │  │  retrieve.py    │    │
│  │  去重/矛盾消解   │  │  混合检索+评分   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
│  ┌─ 维护路径 ──────┐  ┌─ 统计路径 ──────┐    │
│  │  consolidator   │  │  decay.py       │    │
│  │  聚类合并+剪枝   │  │  遗忘曲线+强度   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
├──────────────────────────────────────────────┤
│  embedding.py          │  graph.py           │
│  768d / 1024d 向量编码  │  NetworkX 语义图谱  │
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  向量存储  ·  BM25 全文索引  ·  CRUD          │
└──────────────────────────────────────────────┘

数据文件（~/.engram/）：
├── memories.duckdb     # 向量数据库（单文件，零运维）
├── graph.json          # 语义图谱（JSON 序列化）
└── model_cache/        # 嵌入模型缓存

MCP 도구 인터페이스

중요도 참고

사용자 혜택

1. 에이전트가 당신을 진정으로 '알아봅니다'

매번 대화할 때마다 기술 스택, 코딩 습관, 프로젝트 배경을 다시 설명할 필요가 없습니다. 에이전트는 당신이 Java보다 Go를 선호한다는 점, 프로젝트가 모노레포라는 점, 지난주에 내린 아키텍처 결정을 기억합니다.

2. 지식의 자연스러운 진화

모순 해결 기능 덕분에 에이전트의 인식은 항상 최신 상태입니다. React에서 Vue로 전환했나요? 한 번의 대화로 자동 업데이트됩니다. '에이전트가 무엇을 알아야 하는지' 목록을 수동으로 관리할 필요가 없습니다.

3. 제로 운영

• 오래된 기억을 수동으로 정리할 필요 없음 — 망각 곡선이 자동 삭제

• 중복을 수동으로 병합할 필요 없음 — 통합기가 자동 처리

• 데이터 팽창 걱정 없음 — 12시간마다 자동 유지보수

• 외부 서비스 필요 없음 — DuckDB 단일 파일, 즉시 사용 가능

4. 완전한 프라이버시

모든 데이터는 ~/.engram/에 저장되며, 인터넷 연결이나 업로드 없이 어떤 클라우드 서비스에도 의존하지 않습니다. 임베딩 모델도 로컬에서 실행됩니다. 당신의 기억은 오직 당신의 것입니다.

5. 연상적 발견

그래프 확장을 통해 에이전트는 단순히 '검색된 결과'만 반환하는 것이 아니라, 의미론적 연관성을 따라 직접 매칭되지 않는 관련 지식까지 찾아냅니다. 마치 동료에게 질문했을 때, 질문에 대한 답뿐만 아니라 "맞다, 이건 지난번 그 일과 관련 있어"라고 말해주는 것과 같습니다.

6. 사용할수록 똑똑해짐

회상 강화 메커니즘: 반복적으로 회상되는 기억은 강도가 점점 높아지고 감쇠 속도는 느려집니다. 에이전트는 어떤 지식이 당신에게 가장 가치 있는지 스스로 학습합니다.

빠른 시작

# 安装
pip install mcp-engram

# 初始化（下载模型、创建数据库）
engram-setup

# 按照输出提示将配置块添加到 Claude Code 配置中

Claude Code 설정

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}

CLAUDE.md 통합

프로젝트 CLAUDE.md에 추가:

## Memory Rules

### Step 1 — 先回忆再行动
每次任务开始时，用请求中的关键词调用 `recall_memory`。

### Step 2 — 学到新东西就存
| 情况 | 操作 |
|------|------|
| 全新知识 | `store_memory(content, importance)` |
| 补充已有 | `update_memory(memory_id, merged_content)` |
| 推翻已有 | `update_memory(memory_id, new_content)` |

환경 변수

주요 임계값 요약

LoCoMo 벤치마크 평가

LoCoMo(Snap Research 장기 대화 기억 벤치마크) 기반 검색 품질 평가. LoCoMo는 Mem0/Zep/Memobase/MemMachine 등 제품에서 공통으로 사용하는 평가 표준입니다.

평가 설정

• 데이터셋: locomo10.json (2/10 대화, 233 QA, 적대적 사례 제외)

• 검색: recall() top-k=5

• LLM: DeepSeek-V3.2 / GLM-5.1 (참고: 기준 제품은 GPT-4o-mini 사용)

• 지표: Token-level F1 (LoCoMo 공식 지표) + Hit@5 (LLM 무관 검색 적중률)

Turn Mode — 최적 설정 (bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2)

2단계 검색: recall top-50 → CrossEncoder rerank to top-5, importance=1.0 가중치 보정

Turn Mode — 최적화 경로 (DeepSeek-V3.2)

4단계 최적화 누적 F1 +50.3% (0.29 → 0.44), Hit@5 +26.2pp (51.5% → 77.7%).

Turn Mode — LLM 비교 (all-mpnet-base-v2)

Observation Mode (추상적 사실)

업계 기준 비교

결론: 4단계 최적화 mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44). Hit@5: 51.5% → 77.7%. Mem0(0.67)과의 격차를 56%에서 35%로 축소.

Best Config 요약

권장 설정: bge-m3 (1024d) + bge-reranker-v2-m3 2단계 검색

지표	값	설명
Overall F1	0.4383	Token-level, DeepSeek-V3.2
Overall Hit@5	77.7%	순수 검색 적중률, LLM 무관
Temporal Hit@5	95.2%	시계열 질문에서 뛰어난 성능
최적화 폭	F1 +50.3%, Hit +26.2pp	4단계 누적 (초기 mpnet 대비)

핵심 파라미터: recall top-50 → rerank to top-5, importance=1.0 가중치 보정. 로컬 배포로 클라우드 의존성 제로, GPT-4o-mini를 사용하는 Mem0과의 격차를 35%까지 축소.

개발

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

라이선스

MIT