linksee-memory

로컬 우선 에이전트 메모리 MCP. Claude Code, Cursor, ChatGPT Desktop을 위한 크로스 에이전트 두뇌 — 다른 곳에서는 제공하지 않는 토큰 절약형 파일 diff 캐시 포함.

npm license

기능

대부분의 "에이전트 메모리" 서비스(Mem0, Letta, Zep)는 사실의 단순 목록을 저장합니다. 그래서 에이전트가 "파일 X를 30번 수정함"을 봐도 그 이유를 알 수 없습니다. linksee-memory는 그 '이유(WHY)'를 보존합니다.

이것은 모든 AI 에이전트에게 네 가지 슈퍼파워를 부여하는 모델 컨텍스트 프로토콜(MCP) 서버입니다:

	Mem0 / Letta / Zep	Claude Code 자동 메모리	linksee-memory
크로스 에이전트	△ (클라우드)	❌ Claude 전용	✅ 단일 SQLite 파일
6계층 WHY 구조	❌ 단순 나열	❌ 단순 마크다운	✅ 목표 / 맥락 / 감정 / 구현 / 주의사항 / 학습
파일 diff 캐시	❌	❌	✅ AST 인식, 재읽기 시 50-99% 토큰 절감
능동적 망각	△	❌	✅ 에빙하우스 곡선, 주의사항 계층 보호
로컬 우선 / 개인정보 보호	❌	✅	✅

세 가지 핵심 요소

토큰 절감: read_smart를 통한 sha256 + AST/헤딩/들여쓰기 청킹. 재읽기 시 diff만 반환합니다. 일반적인 TS 파일 수정 시 86% 절감, 변경 없는 재읽기 시 99% 절감 측정.
크로스 에이전트 이식성: ~/.linksee-memory/memory.db에 단일 SQLite 파일로 저장. Claude Code, Cursor, ChatGPT Desktop에서 동일한 두뇌 공유.
WHY 중심 구조화 메모리: 6개의 명시적 계층(목표 / 맥락 / 감정 / 구현 / 주의사항 / 학습). "목표 없는 단순 사실 메모리는 무용지물"이라는 문제를 해결합니다.

설치

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

또는 npx를 임시로 사용:

npx linksee-memory             # starts the MCP server on stdio

기본 데이터베이스는 ~/.linksee-memory/memory.db에 위치합니다. LINKSEE_MEMORY_DIR 환경 변수로 경로를 변경할 수 있습니다.

Claude Code에 등록

claude mcp add -s user linksee -- npx -y linksee-memory

Claude Code를 재시작하세요. 도구는 mcp__linksee__remember, mcp__linksee__recall, mcp__linksee__recall_file, mcp__linksee__read_smart, mcp__linksee__forget, mcp__linksee__consolidate로 나타납니다.

선택 사항: 모든 세션 자동 캡처 (Stop hook)

~/.claude/settings.json에 추가하여 모든 Claude Code 세션을 로컬 두뇌에 자동으로 기록하세요:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

각 턴 종료 시 약 100ms가 소요됩니다. 실패 시 조용히 처리됩니다(Claude Code는 절대 차단되지 않음). 로그는 ~/.linksee-memory/hook.log에 저장됩니다.

도구

도구	목적
`remember`	엔티티에 대해 6개 계층 중 하나로 메모리 저장
`recall`	FTS5 + 히트 점수 + 모멘텀 복합 랭킹, JP/EN 트라이그램 검색
`recall_file`	모든 세션에 걸친 파일의 전체 수정 이력과 수정별 사용자 의도 맥락 조회
`read_smart`	Diff 전용 파일 읽기. 첫 읽기 시 전체 내용 반환, 변경 없는 재읽기 시 약 50 토큰, 실제 수정 시 변경된 청크만 반환
`forget`	명시적 삭제 또는 망각 위험도(중요도 × 히트 × 경과 시간)에 따른 자동 삭제
`consolidate`	수면 모드 압축: 중요도가 낮은 오래된 메모리를 클러스터링하여 보호된 학습 계층 요약으로 변환

6가지 메모리 계층

각 엔티티(사람 / 회사 / 프로젝트 / 파일 / 개념)는 6개 계층에 걸쳐 메모리를 가질 수 있습니다. 계층은 카테고리가 아닌 의미를 인코딩합니다:

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

주의사항(caveat) 메모리는 망각으로부터 자동 보호됩니다(고통스러운 교훈, 절대 손실되지 않음).
목표(goal) 메모리는 목표가 활성화되어 있는 동안 감쇠를 우회합니다.

아키텍처

단일 SQLite 파일(better-sqlite3 + JP/EN용 FTS5 트라이그램 토크나이저)이 5개 계층을 포함합니다:

계층 1 — entities (사실: 사람 / 회사 / 프로젝트 / 개념 / 파일)
계층 2 — edges (연관성, 그래프 인접성)
계층 3 — memories (엔티티별 6계층 구조화된 의미)
계층 4 — events (히트 / 모멘텀 계산을 위한 시계열 로그)
계층 5 — file_snapshots + session_file_edits (diff 캐시 + 대화↔파일 연결)

대화↔파일 연결이 핵심입니다. Stop hook에 의해 캡처된 모든 파일 수정은 수정을 유도한 사용자 메시지와 함께 저장됩니다. 따라서 recall_file("server.ts")를 호출하면 "이 파일은 3일 동안 30번 수정되었으며, 각 변경을 유도한 실제 사용자 지침은 다음과 같습니다"라는 결과를 반환합니다.

설계 선택 이유

로컬 우선 — 대화 기록은 비공개입니다. 기기 밖으로 나가는 데이터는 없습니다.
단일 파일 — memory.db는 하나의 이식 가능한 아티팩트입니다. 백업 = 파일 복사.
MCP stdio — MCP를 지원하는 모든 에이전트와 작동하며, 호스트별 플러그인이 필요 없습니다.
검증된 스키마 재사용 — heat_score / momentum_score는 프로덕션 영업 인텔리전스 코드베이스에서 가져왔습니다. 규칙 기반이며, 핫 패스에서 LLM 의존성이 없습니다.

로드맵

✅ 핵심 6개 MCP 도구 (remember / recall / recall_file / forget / consolidate / read_smart)
✅ Claude Code용 Stop-hook 자동 캡처
✅ JP/EN 트라이그램 FTS5
🚧 Read를 자동 가로채는 PreToolUse 훅 (제로 설정 토큰 절감)
🚧 Cursor + ChatGPT Desktop 어댑터
🔮 임베딩 백엔드(Ollama / API 등) 선택 후 sqlite-vec을 통한 벡터 검색
🔮 선택적 익명 텔레메트리 → MCP 품질 인텔리전스 계층

Claude Code 자동 메모리와의 비교

Claude Code는 ~/.claude/projects/<path>/memory/*.md에 내장 메모리 기능을 제공합니다(사용자 선호도를 위한 단순 마크다운 노트). linksee-memory는 이를 보완합니다:

자동 메모리 = "내가 X를 선호한다는 것을 기억해"라는 스크랩북
linksee-memory = 파일 diff 캐시와 수정별 WHY를 포함한 구조화된 크로스 에이전트 두뇌

둘 다 사용하세요.

텔레메트리 (옵트인, 기본값 꺼짐)

linksee-memory는 어떤 MCP 서버와 워크플로우가 실제로 현장에서 작동하는지 이해하기 위해 옵트인 익명 텔레메트리를 제공합니다. 명시적으로 활성화하지 않으면 아무것도 전송되지 않습니다. 대화 내용, 파일 내용, 엔티티 이름, 프로젝트 경로 등은 절대 전송되지 않습니다.

활성화

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

전송되는 데이터 (레벨 1 계약)

각 Claude Code 세션이 종료된 후, Stop hook은 https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee로 다음 필드만 포함된 POST 요청을 한 번 보냅니다:

필드	예시	내용
`anon_id`	`d7924ced-3879-…`	첫 옵트인 시 로컬에서 생성된 무작위 UUID. `~/.linksee-memory/telemetry-id`에 저장됨 — 삭제 시 재설정
`linksee_version`	`0.0.3`	패키지 버전
`session_turn_count`	`120`	세션 턴 수
`session_duration_sec`	`3600`	세션 지속 시간
`file_ops_edit/write/read`	`12, 2, 40`	작업 횟수
`mcp_servers`	`["kansei-link","freee","slack"]`	설정된 MCP 서버 이름 (`~/.claude.json`에서 가져옴). 이름만 전송 — 명령 경로 절대 아님
`file_extensions`	`{".ts":60,".md":30}`	다루어진 파일 확장자 분포
`read_smart_`, `recall_`	counts	도구 사용 카운터

절대 전송되지 않는 데이터:

❌ 대화 메시지 (사용자 또는 어시스턴트)
❌ 파일 내용
❌ 엔티티 이름, 프로젝트 이름, 파일 경로, URL
❌ 메모리 계층 텍스트 (목표 / 맥락 / 감정 / 구현 / 주의사항 / 학습)
❌ 인증 토큰, API 키, 비밀 정보
❌ IP 주소 (남용 방지를 위한 일방향 해시만 사용)

요청 이유

집계된 MCP 사용 데이터는 KanseiLink 프로젝트가 실제 개발자에게 어떤 에이전트 통합이 효과적인지 순위를 매기는 데 도움을 줍니다. 기여를 원하신다면 LINKSEE_TELEMETRY=basic을 설정하는 데 1초면 충분하며, 전체 MCP 생태계를 개선하는 데 도움이 됩니다.

전체 페이로드 스키마와 검증 로직은 오픈 소스입니다. 기기에서 정확히 무엇이 나가는지 확인하려면 src/lib/telemetry.ts를 읽어보세요.

라이선스

MIT — Synapse Arrows PTE. LTD.

Linksee Memory