mcp-brain-tools

내장된 신선도 추적 및 간격 반복(spaced repetition) 기능을 통해 AI 에이전트에게 지속적인 메모리를 제공하는 MCP 서버입니다. Elasticsearch를 기반으로 합니다.

단순한 키-값 메모리 저장소와 달리, mcp-brain-tools는 각 지식 조각이 얼마나 오래되었는지 추적하고, 검토가 필요한 항목을 표시하며, 에이전트가 정보를 확인하여 신선하게 유지할 수 있도록 합니다. 이는 간격 반복이 인간의 지식 유지에 도움을 주는 방식에서 영감을 받았습니다.

기능

간격 반복 신선도 — 각 엔티티에는 확인 시 두 배로 늘어나는(최대 365일) 검토 간격이 있습니다. 신뢰도 라벨(신선함/보통/노후화/오래됨/보관됨)은 에이전트에게 무엇을 신뢰해야 하는지 알려줍니다.
점진적 검색 — 쿼리는 신선한 결과를 먼저 반환하며, 필요할 때만 자동으로 더 오래된 데이터를 포함하도록 확장됩니다.
엔티티로서의 관찰 — 각 관찰은 고유한 신선도 수명 주기를 가지므로, "빌드 깨짐"(1일 검토)과 "2015년 설립"(365일 검토)은 독립적으로 노후화됩니다.
메모리 영역 — 프로젝트, 팀 또는 도메인별로 지식을 격리합니다.
AI 기반 필터링 — 선택적인 Groq 통합을 통해 관련성별로 검색 결과의 점수를 매깁니다.
DRY(Don't Repeat Yourself) 설계 — 도구 설명은 에이전트가 코드, git 또는 문서에 이미 있는 내용을 저장하지 않도록 안내합니다.

Related MCP server: Logseq MCP Tools

설정

사전 요구 사항

Node.js >= 18
Docker (Elasticsearch용) 또는 원격 Elasticsearch 인스턴스

설치 및 빌드

npm install
npm run build

Elasticsearch 시작

npm run es:start

또는 ES_NODE 환경 변수를 통해 자신의 인스턴스를 지정하십시오.

MCP 클라이언트 구성

Claude Code, Claude Desktop 또는 기타 MCP 클라이언트 구성에 추가하십시오:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-brain-tools/dist/index.js"],
      "env": {
        "ES_NODE": "http://localhost:9200",
        "GROQ_API_KEY": "your-key-here"
      }
    }
  }
}

GROQ_API_KEY는 선택 사항이며, AI 기반 검색 필터링 및 영역 관련성 점수 매기기를 활성화합니다.

자동 메모리 후크 설치 (Claude Code 전용)

메모리 후크는 모든 사용자 메시지에서 실행되며 관련 컨텍스트를 자동으로 삽입합니다. 에이전트의 협조가 필요하지 않습니다.

~/.claude/settings.json에 추가하십시오:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/mcp-brain-tools/dist/memory-hook.js"
          }
        ]
      }
    ]
  }
}

이 후크는 동일한 ES_NODE, AI_API_KEY/GROQ_API_KEY, AI_API_BASE 및 AI_MODEL 환경 변수를 사용합니다(설정의 env 블록에 설정하거나 셸 프로필에서 내보내십시오).

AI_API_BASE는 기본적으로 Groq의 엔드포인트로 설정되지만, 모든 OpenAI 호환 API URL을 허용합니다.

작동 방식

엔티티 및 관찰

엔티티는 사람, 프로젝트, 결정, 사실 등 기억할 가치가 있는 모든 것을 나타냅니다. 각 엔티티는 다음을 가집니다:

이름 및 유형
간격 반복 필드: verifiedAt, reviewInterval, nextReviewAt
신선도에서 계산된 신뢰도 라벨: 1 - (daysSinceVerified / reviewInterval)

관찰은 is_observation_of 관계로 연결된 별도의 엔티티로 저장됩니다. 각 관찰은 고유한 검토 주기를 가집니다:

Entity: "iaptic-server" (type: Project, reviewInterval: 30 days)
  <- "iaptic-server: uses TypeScript" (reviewInterval: 180 days)
  <- "iaptic-server: migration in progress" (reviewInterval: 7 days)

신선도 수명 주기

엔티티 생성 — confidence: "fresh", 기본 검토 7일
검토 날짜 경과 — confidence: "aging", needsReview: true
에이전트 확인 (verify_entity를 통해) — 간격이 두 배가 되고, 신뢰도가 신선함으로 재설정됨
장기 연체 — confidence: "stale" 후 "archival", 기본 검색에서 제외됨

점진적 검색

검색 시 서버는 세 단계를 사용합니다:

freshness >= 0 — 신선하고 보통인 엔티티
freshness >= -2 — 노후화되고 오래된 엔티티 추가
필터 없음 — 보관된 엔티티 추가

이렇게 하면 결과가 깔끔하게 유지되면서도 아무것도 영구적으로 손실되지 않습니다.

MCP 도구

도구	설명
`create_entities`	선택적 관찰 및 reviewInterval을 포함하여 엔티티 생성
`update_entities`	기존 엔티티 업데이트
`delete_entities`	엔티티 삭제 (선택적 캐스케이드 포함)
`add_observations`	고유한 신선도를 가진 별도의 엔티티로 관찰 추가
`verify_entity`	엔티티가 여전히 정확한지 확인하고 검토 간격 연장
`search_nodes`	점진적 신선도 필터링을 사용하여 검색
`open_nodes`	신선도 메타데이터와 함께 이름으로 특정 엔티티 가져오기
`get_recent`	최근에 액세스한 엔티티 가져오기
`create_relations`	엔티티 간의 관계 생성
`delete_relations`	관계 제거
`inspect_knowledge_graph`	잠정적인 답변을 포함한 AI 기반 엔티티 검색
`inspect_files`	AI 기반 파일 내용 검사
`list_zones`	메모리 영역 나열 (AI 관련성 점수 포함)
`create_zone` / `delete_zone`	메모리 영역 관리
`copy_entities` / `move_entities`	영역 간 엔티티 전송
`merge_zones`	충돌 해결을 포함하여 영역 병합
`zone_stats`	영역의 엔티티/관계 수 가져오기
`mark_important`	엔티티 관련성 점수 향상
`get_time_utc`	현재 UTC 시간 가져오기

환경 변수

변수	기본값	설명
`ES_NODE`	`http://localhost:9200`	Elasticsearch URL
`ES_USERNAME`	—	Elasticsearch 사용자 이름
`ES_PASSWORD`	—	Elasticsearch 비밀번호
`GROQ_API_KEY`	—	AI 필터링을 위한 Groq API 키
`GROQ_MODELS`	`openai/gpt-oss-120b,llama-3.3-70b-versatile`	쉼표로 구분된 모델 목록
`KG_INDEX_PREFIX`	`knowledge-graph`	Elasticsearch 인덱스 접두사
`KG_DEFAULT_ZONE`	`default`	기본 메모리 영역
`DEBUG`	`false`	디버그 로깅 활성화

권장 에이전트 지침

에이전트가 메모리 서버를 적극적으로 사용하도록 하려면 CLAUDE.md(또는 동등한 지침 파일)에 다음과 같은 내용을 추가하십시오:

## Memory

Use MCP Memory (`mcp__memory__*` tools) — a shared knowledge graph across all agents, projects, and computers.

**When to SAVE (immediately, before moving on):**
- Something you tried didn't work (non-transient) → save what failed and why, so no agent repeats it
- A decision was made (architectural, design, workflow) → save the decision and the reason
- The user corrects you or gives explicit instructions → save the rule
- You learn something non-obvious that took effort to discover → save it

**When to SEARCH (before starting, not after failing):**
- **At the start of every non-trivial task** — search before thinking, not after hitting a wall
- About to try an approach that might have been attempted before → search first
- User references something from a past session → search before asking

**Rules:**
- Skip anything easy to find in code, git log, or docs
- Use the project name as the zone for project-specific knowledge; `default` for general knowledge
- Keep entries short — the AI filters server-side, so be generous rather than selective
- Short `reviewInterval` (e.g. 3–7 days) for volatile facts; longer (30–180) for stable ones

핵심 통찰력: 에이전트는 도구가 무엇을 하는지에 대한 설명뿐만 아니라 명시적인 트리거 기반 지침("X일 때 Y를 수행하라")이 필요합니다.

개발

npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm run test:jest      # Run Jest tests
npm run es:start       # Start Elasticsearch
npm run es:stop        # Stop Elasticsearch
npm run es:reset       # Wipe data and restart
npm run import         # Import from JSON
npm run export         # Export to JSON

라이선스

MIT

Elasticsearch Knowledge Graph for MCP