Kairn

AI 어시스턴트를 위한 컨텍스트 인식 지식 엔진.

상태: 알파. API와 CLI는 기능하며 테스트되었습니다(개발 섹션 참조). 그러나 인터페이스는 릴리스 간에 변경될 수 있습니다. 피드백과 이슈를 환영합니다.

다른 도구는 AI에 메모리를 제공합니다. Kairn은 지능형 컨텍스트 라우팅을 갖춘 지식 그래프를 제공합니다. 무엇을, 언제, 얼마나 로드할지 알고 있어 AI가 집중력을 유지하고 압도되지 않도록 합니다.

pip install kairn-ai
kairn init ~/brain
kairn serve ~/brain

Claude Code에 한 줄로 추가하세요:

claude mcp add kairn -- kairn serve ~/brain

또는 Python 설정 없이 원클릭 번들로 설치하세요: 최신 릴리스에서 .mcpb 파일을 다운로드하고 Claude Desktop과 같은 번들 인식 앱으로 열면 됩니다.

다른 클라이언트는 아래 빠른 시작을 참조하세요. Kairn이 처음이신가요? 첫 5분으로 이동하세요.

설치 경로

번들은 자체 Kairn 소스를 포함하지 않습니다. kairn-ai를 종속성으로 선언하고 호스트가 uv로 해결하므로 번들 설치와 pip install은 동일한 코드를 실행합니다. 데이터베이스 위치는 번들 설치 시 구성할 수 있으며 기본값은 ~/.kairn이고 기기를 벗어나지 않습니다.

Related MCP server: Mnemosyne

왜 Kairn인가?

모든 AI 대화는 처음부터 시작됩니다. 이전의 통찰, 결정, 패턴 - 모두 사라집니다. 기존 메모리 도구는 관계를 표현하거나 올바른 컨텍스트를 올바른 시점에 표면화할 수 없는 평면 키-값 쌍을 저장합니다.

Kairn은 다릅니다:

• 컨텍스트 라우터 + 점진적 공개 - 키워드를 기반으로 관련 하위 그래프를 자동으로 로드하며, 요약부터 시작하여 필요할 때만 세부 사항으로 들어갑니다. 다른 도구는 이 기능을 제공하지 않습니다.

• FTS5를 갖춘 지식 그래프 - 평면 저장이 아닙니다. 노드 간의 유형화된 관계(depends-on, resolves, causes)와 출처 추적 및 전체 텍스트 검색을 제공합니다.

• 경험 감쇠 + 자동 승격 - 경험은 시간이 지남에 따라 관련성을 잃습니다(생물학적 감쇠 모델). 자주 액세스되는 경험은 영구 지식으로 자동 승격됩니다. AI는 중요하지 않은 것을 자연스럽게 잊습니다.

• 22개의 MCP 도구 - Claude Desktop, Cursor, VS Code, Windsurf 및 모든 MCP 클라이언트에서 작동합니다. 5-동사 관계 판단을 위한 kn_judge와 읽기 전용 상태 진단을 위한 kn_doctor를 포함합니다.

• 작업공간별 격리 - 각 작업공간은 자체 격리된 SQLite 저장소입니다. 팀 배포를 위해 JWT 인증 및 역할 기반 액세스 제어(소유자 / 관리자 / 기여자 / 읽기 전용)가 제공됩니다.

빠른 시작

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

Cursor

.cursor/mcp.json에 추가:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"],
      "env": {
        "KAIRN_LOG_LEVEL": "WARNING"
      }
    }
  }
}

VS Code

.vscode/mcp.json에 추가:

{
  "servers": {
    "kairn": {
      "type": "stdio",
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

편집기를 다시 시작하세요. Kairn의 22개 도구가 MCP 섹션에 나타납니다.

첫 5분

안내된 첫 실행, 처음부터 끝까지:

pip install kairn-ai
kairn init ~/brain              # creates the workspace + database

위의 한 줄(또는 클라이언트의 빠른 시작 스니펫)을 추가한 다음 클라이언트를 다시 시작하세요. 연결되면 어시스턴트에게 무언가를 기억하라고 요청하세요:

"분석 서비스에 동시 쓰기 때문에 SQLite 대신 Postgres를 선택했다는 것을 기억해."

이것은 내부적으로 kn_learn을 호출하며 다음과 같은 JSON 봉투를 반환합니다(실제 실행에서 캡처, kairn learn - 도구의 CLI 미러 - 통해):

{"_v": "1.0", "stored_as": "node", "node_id": "002d9c22", "experience_id": "d0710c2f", "type": "decision", "confidence": "high", "namespace": "knowledge", "candidates": []}

새 세션을 시작하고 같은 것을 회상하라고 요청하세요 - kn_recall을 호출하여 방금 저장한 것을 표면화하며 다시 설명할 필요가 없습니다:

{"_v": "1.0", "count": 2, "results": [
  {"source": "node", "id": "002d9c22", "name": "Decision: we chose Postgres over SQLite for the analytics service beca", "type": "learned_decision", "description": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "relevance": 1.0},
  {"source": "experience", "id": "d0710c2f", "type": "decision", "content": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "confidence": "high", "relevance": 1.0}
]}

kn_learn은 영구 그래프 노드와 감쇠 경험을 모두 저장합니다(높은 신뢰도는 둘 다 수행, 신뢰도 라우팅 참조); kn_recall은 세 단어 주제에서 둘 다 찾았습니다.

언제든지 kairn status ~/brain을 스모크 테스트로 실행하세요 - JSON 통계 블록(노드/엣지/경험 수)을 출력하면 작업공간이 정상입니다. 수동으로 하는 대신 모든 핵심 기능의 스크립트 투어를 원하시나요? kairn demo ~/brain을 실행하세요 - 노드 생성, 쿼리, 경험 저장, 학습, 회상, 컨텍스트를 약 30초 안에 진행합니다.

어떤 도구를 언제 사용할까

22개 도구는 첫날에 모두 기억하기에는 많습니다. 대부분의 세션은 다음만 필요합니다:

나머지(kn_crossref, kn_related, kn_connect, kn_judge, kn_project/kn_projects/kn_log, kn_idea/kn_ideas, kn_promote_pending, kn_prune, kn_remove, kn_status, kn_doctor)는 고급 사용입니다 - 기본을 넘어선 후 아래 전체 22개 도구 참조를 확인하세요.

22개 도구 (kn_ 접두사)

모든 도구는 JSON 응답으로 MCP 프로토콜을 따릅니다.

그래프 (6)

프로젝트 메모리 (3)

경험 메모리 (5)

아이디어 (2)

지능 (5)

진단 (1)

리소스 및 프롬프트

리소스(MCP 클라이언트용 읽기 전용 컨텍스트):

• kn://status - 그래프 개요, 활성 프로젝트

• kn://projects - 최근 진행 상황이 포함된 모든 프로젝트

• kn://memories - 최근 관련성 높은 경험

프롬프트(세션 관리):

• kn_bootup - 활성 프로젝트, 최근 진행 상황, 주요 기억 로드(세션 시작)

• kn_review - 세션 요약 및 다음 단계 제안(세션 종료)

작동 방식

아키텍처

Any MCP Client (Claude, Cursor, VS Code)
        │
        ▼ MCP Protocol (stdio)
FastMCP Server (22 tools)
        │
   ┌────┼────┐
   ▼    ▼    ▼
Graph  Memory  Intelligence
Engine Engine  Layer
   │    │      │
   └────┼──────┘
        ▼
   SQLite + FTS5
   (per-workspace)

감쇠 모델

경험은 지수적으로 관련성이 감소합니다:

relevance(t) = initial_score × e^(-decay_rate × days)

반감기는 추측이 아닌 프로덕션 경험 저장소의 실제 접근 꼬리 분포를 기준으로 보정됩니다(한 가지 예외: preference는 접근 이력이 없는 새로운 유형이므로, 실제 데이터가 축적될 때까지 그 값은 문서화된 초기 추정치입니다).

kn_learn을 통한 신뢰도 라우팅:

• high → 영구 노드 + 경험(감쇠 없음)

• medium → 2배 감쇠 경험

• low → 4배 감쇠 경험

• 자동 승격: 5회 이상 접근 → 영구 노드

• 노드 접근 추적: kn_recall, kn_context, kn_crossref는 접근된 노드를 기록하여 감쇠 및 승격 파이프라인에 공급

벤치마크

Kairn은 LongMemEval-S에서 전체 56.2% 를 기록했습니다(500/500개 질문 채점, GPT-4o 리더 + 심사자, 단일 실행, 오류 0건). 이는 실제 카테고리별 수치이며, 나쁜 수치도 포함합니다 - 각 빨간 셀은 해당 진단으로 연결됩니다:

500개 질문에는 30개의 기권 변형(정답이 거절인 경우)이 포함되어 있으며, 이는 위 카테고리 내에 집계되고 별도로 채점됩니다: Kairn은 이 중 96.7% 에서 올바르게 거절합니다.

회상 지연 시간은 쿼리당 ~1.4ms입니다(FTS5, 프로세스 내, 네트워크 없음). 프로토콜, 정직성 노트, 재현 절차: BENCHMARKS.md.

이 스코어카드는 최신 상태를 유지합니다: 회상을 건드리는 모든 릴리스는 이 수치를 재게시하며, 약점 셀은 수치가 실제로 움직일 때까지 보드에 남아 있습니다. 선별된 실행도, 숨겨진 카테고리도 없습니다.

CLI

kairn init <path>              # Initialize workspace
kairn serve <path>             # Start MCP server (stdio)
kairn status <path>            # Graph stats
kairn demo <path>              # Interactive tutorial
kairn benchmark <path>         # Local performance benchmarks (latency, not LongMemEval)
kairn token-audit <path>       # Audit tool token usage
kairn import git <path> <repo>...  # Import git commit history (zero-LLM, offline)
kairn import claude-code <path>    # Import Claude Code session history (zero-LLM, offline)

기록 가져오기

kairn import git <workspace> <repo>...는 하나 이상의 로컬 git 저장소에서 Kairn 저장소를 백필합니다 - LLM 호출 없음, 네트워크 호출 없음. Conventional-commit 접두사는 경험 유형에 매핑됩니다(fix: -> solution, feat:/refactor:/perf: -> pattern, 그 외 모든 것 -> decision); 병합 커밋은 건너뜁니다. 가져온 경험은 전용 imported-git 네임스페이스에 저장되어 유기적 지식과 분리되므로 항상 구분 가능하며 잘못된 가져오기는 완전히 되돌릴 수 있습니다.

kairn import git ~/brain ~/code/my-project --dry-run   # Preview first
kairn import git ~/brain ~/code/my-project              # Then import for real
kairn import git ~/brain ~/code/proj-a ~/code/proj-b --since 2026-01-01

멱등적 - 재실행 시 아직 가져오지 않은 커밋만 가져오므로, 저장소 기록이 성장함에 따라 다시 실행해도 안전합니다.

Claude Code 트랜스크립트

kairn import claude-code <workspace>는 기존 Claude Code 세션 기록에서 Kairn 저장소를 백필합니다. 역시 비용 $0이며 완전히 오프라인입니다. --root를 지정하지 않으면 ~/.claude/projects(두 번째 계정이 있으면 ~/.claude-secondary/projects도)를 스캔합니다. --root PATH는 반복 가능한 재정의입니다. 가져온 경험은 자체 imported-claude-code 네임스페이스에 저장되어 유기적 지식과 구분되며 잘못된 가져오기는 되돌릴 수 있습니다.

kairn import claude-code ~/brain --dry-run              # Review exactly what would be stored
kairn import claude-code ~/brain                        # Import (prompts once before writing)
kairn import claude-code ~/brain --root ~/other/projects --since 2026-01-01 --yes

저장되는 내용(거친 모드): 세션당 하나의 경험 - 세션 제목과 해당 세션의 첫 프롬프트. 이는 세밀한 결정별 추출이 아닌 의도적으로 저상세·고정밀 요약입니다: LLM 없는 규칙 기반 추출기는 포착된 결정과 일반적인 계획 대화를 안정적으로 구분할 수 없으므로, import claude-code는 노이즈가 많은 조각 대신 깨끗한 세션 수준 포인터를 가져옵니다. 전체 트랜스크립트 아카이브가 아니며 일회성 마이그레이션도 아닙니다 - 멱등적이며 기록이 성장함에 따라 재실행하도록 설계되었습니다.

개인정보 보호. 저장되는 모든 문자열은 먼저 결정적 비밀정보 리댁터를 통과합니다 (API 키, Authorization/Bearer 헤더, password=/token=/secret= 할당, 일반적인 벤더 키 형태, 개인 키 블록, URL 내장 자격 증명). 도구 출력과 도구 호출 블록은 절대 읽지 않으며, 사용자의 프롬프트 텍스트만 읽습니다. 리댁터는 심층 방어이지 유일한 통제 수단이 아닙니다: 실제(드라이런이 아닌) 실행은 명시적 확인 뒤에만 허용되며, --dry-run은 아무것도 기록되기 전에 리댁션 후 정확한 텍스트를 보여줍니다. 리댁션은 규칙 집합에 의해 제한되므로, 첫 실제 가져오기 전에 --dry-run 검토를 권장합니다; 어떤 것도 기기를 떠나지 않습니다.

구성

KAIRN_LOG_LEVEL=INFO|DEBUG|WARNING    # Default: WARNING
KAIRN_DB_PATH=~/brain/.kairn         # Default: {workspace}/.kairn
KAIRN_CACHE_SIZE=100                  # LRU cache entries
KAIRN_JWT_SECRET=<your-secret>        # Required for team features

개발

git clone https://github.com/primeline-ai/kairn
cd kairn
pip install -e ".[dev,team]"
pytest tests/ -v --cov
ruff check src/ && ruff format src/

프로젝트 구조

src/kairn/
├── server.py              # FastMCP server + 22 tools
├── cli.py                 # CLI commands
├── config.py              # Configuration
├── core/
│   ├── graph.py           # GraphEngine (6 tools)
│   ├── memory.py          # ProjectMemory (3 tools)
│   ├── experience.py      # ExperienceEngine (4 tools)
│   ├── ideas.py           # IdeaEngine (2 tools)
│   ├── intelligence.py    # IntelligenceLayer (5 tools)
│   └── router.py          # ContextRouter
├── storage/
│   ├── base.py            # Storage interface
│   └── sqlite_store.py    # SQLite + FTS5 implementation
├── models/                # Data models
├── events/                # Event bus
└── auth/                  # JWT + RBAC (team feature)

성능

최신 하드웨어에서의 일반적인 작업 시간:

사용처

라이선스

MIT

PrimeLine 생태계의 일부

@PrimeLineAI · primeline.cc · 무료 가이드