local-rag

에이전트는 모든 세션을 아무것도 모른 채 시작합니다. 파일 이름을 추측하고, 키워드를 grep하고, 관련 없는 파일에 컨텍스트를 낭비하며, 어제 논의한 모든 것을 잊어버립니다.

실제 프로젝트 하나에서 일반적인 프롬프트 하나가 종단 간 380K 토큰과 ~12초를 소모했습니다.

mimirs로 인덱싱한 후에는: 91K 토큰, ~3초 — 해당 코드베이스에서 76% 감소입니다. 수치는 리포지토리 크기, 쿼리, 모델에 따라 달라질 수 있습니다.

빠른 시작

1. 사전 요구 사항

Bun (curl -fsSL https://bun.sh/install | bash)와, macOS에서는 최신 SQLite가 필요합니다 — Apple에 번들된 SQLite는 확장 기능을 지원하지 않습니다:

brew install sqlite

Linux와 Windows에는 이미 호환되는 SQLite가 포함되어 있습니다.

2. 편집기 설정 (자동)

bunx mimirs init --ide claude   # or: cursor, windsurf, copilot, jetbrains, all

이것은 MCP 서버 구성, 편집기 규칙, .mimirs/config.json, .gitignore 항목을 생성합니다. --ide all로 실행하면 지원되는 모든 편집기를 한 번에 설정할 수 있습니다.

init은 Claude Code, Cursor, Windsurf, Copilot, JetBrains (Junie)를 지원합니다. 그 외의 경우 — Codex, Zed, 사용자 정의 클라이언트 — 아래 스니펫 중 하나를 복사하세요.

3. 편집기 설정 (수동 참조)

mimirs MCP 서버는 stdio를 통해 실행됩니다. 모든 클라이언트에는 동일한 세 가지가 필요합니다: command (bunx), args (["mimirs@^1", "serve"]), 그리고 프로젝트 루트를 가리키는 RAG_PROJECT_DIR 환경 변수입니다.

@^1이지 @latest가 아닌 이유는? 이 범위는 1.x에 머물게 하므로 버그 수정과 새 기능은 여전히 자동으로 도착하지만, 호환성을 깨는 변경이 포함된 미래의 2.0은 요청하지 않는 한 절대 설치되지 않습니다. 주요 버전을 올리려면 인수를 편집하거나 bunx mimirs init을 다시 실행하세요. 이미 구성에 mimirs@latest가 있다면 bunx mimirs init을 다시 실행하면 mimirs@^1로 다시 작성됩니다.

"command not found: bunx" / 서버 시작 실패 (그런데 터미널에서는 bunx가 동작한다면)? Dock 또는 데스크톱 런처에서 시작된 편집기는 셸 프로필을 로드하지 않으므로 ~/.bun/bin이 PATH에 없습니다. 아래 스니펫에서 bunx 대신 which bunx의 절대 경로를 command로 사용하세요. bunx mimirs init은 절대 경로를 자동으로 기록합니다(기존 구성을 고치려면 다시 실행하세요). bunx mimirs doctor는 이 문제를 감지합니다.

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Windsurf는 프로젝트가 아닌 홈 디렉터리에서 MCP 서버를 읽습니다. JetBrains 플러그인 변형은 ~/.codeium/mcp_config.json을 사용합니다.

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code의 Copilot은 mcpServers가 아닌 servers 맵과 type 필드를 사용합니다.

{
  "servers": {
    "mimirs": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Codex는 JSON이 아닌 TOML을 사용하며 ~/.codex/config.toml에서 읽습니다. 프로젝트당 하나의 블록입니다 — 여러 리포지토리를 연결하려면 고유한 테이블 이름을 선택하세요 (mimirs-frontend, mimirs-api 등).

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]
env = { RAG_PROJECT_DIR = "/absolute/path/to/your/project" }

또는 동일하게, 확장된 env 테이블을 사용한 형태:

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]

[mcp_servers.mimirs.env]
RAG_PROJECT_DIR = "/absolute/path/to/your/project"

프로젝트가 읽기 전용 마운트에 있다면 RAG_DB_DIR을 쓰기 가능한 위치로 설정하세요. 인덱스는 <project>/.mimirs/ 대신 그 위치에 저장됩니다.

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/read/only/project",
        "RAG_DB_DIR": "/home/me/.cache/mimirs/myproject"
      }
    }
  }
}

4. 첫 인덱스

MCP 서버는 첫 번째 쿼리에서 지연 인덱싱을 수행하므로, 연결만 되면 에이전트에게 무엇이든 물어보기만 하면 됩니다. 인덱스를 미리 강제로 생성하려면 (대형 리포지토리에 유용):

bunx mimirs index            # current directory
bunx mimirs status           # how many files, chunks, embeddings

5. 데모 사용해 보기 (선택 사항)

bunx mimirs demo

Related MCP server: codeix

수동 워크플로 (init 없이)

init은 편의 기능입니다: 편집기를 연결합니다 (MCP 구성, 에이전트 규칙, .gitignore, .mimirs/config.json). 인덱스를 만들지는 않으며, 아래 내용 중 어떤 것도 init이 필요하지 않습니다 — 인덱스와 기본 구성은 처음 인덱싱하거나 쿼리할 때 자동으로 생성됩니다.

1. MCP 서버를 직접 추가합니다. 위의 수동 참조에서 클라이언트에 맞는 스니펫을 가져다 쓰세요: command: "bunx", args: ["mimirs@^1", "serve"], 그리고 프로젝트 루트를 가리키는 RAG_PROJECT_DIR. 이것이 MCP 설정의 전부입니다.

init이 없으면 에이전트 규칙 파일이 없으므로 어시스턴트가 도구의 존재를 알지 못합니다. 프롬프트에서 mimirs를 언급하거나 CLAUDE.md의 도구 목록을 편집기 규칙에 복사하세요.

2. 인덱스를 생성합니다. MCP 서버는 첫 번째 도구 호출에서 지연 인덱싱을 수행하므로 에이전트를 통해서는 이 단계를 건너뛸 수 있습니다. 인덱스를 미리 생성하려면 (대형 리포지토리에서 권장하며, 아래 CLI search/read 전에 필요):

bunx mimirs index                                # current directory
bunx mimirs index /path/to/repo                  # a specific directory
bunx mimirs index --patterns "src/**/*.ts,*.md"  # restrict to globs
bunx mimirs status                               # files, chunks, embeddings

init도 구성 파일도 필요 없습니다 — 기본값이 적용되고 인덱스는 <project>/.mimirs/에 기록됩니다.

3. CLI에서 쿼리합니다. 현재 디렉터리의 인덱스를 대상으로 하는 두 개의 읽기 명령이 있습니다 (다른 위치를 지정하려면 --dir을 사용하세요):

# Where is it? — ranked file paths + snippet previews
bunx mimirs search "where is auth handled" --top 10

# What is it? — the actual matching code chunks (functions, classes, sections)
bunx mimirs read "jwt validation" --top 8 --threshold 0.3

범위는 --ext .ts,.tsx, --in src,packages/core, 또는 --exclude tests로 지정하세요. 참고: CLI search/read는 자동 인덱싱을 하지 않습니다 — 먼저 mimirs index를 실행하세요 (MCP 서버만 요청 시 인덱싱합니다).

Claude Code 플러그인

더 깊은 통합을 위해 mimirs는 Claude Code 플러그인으로도 사용할 수 있습니다. Claude Code 세션에서:

/plugin marketplace add https://github.com/TheWinci/mimirs.git
/plugin install mimirs

이 플러그인은 MCP 서버, 세 가지 훅 — SessionStart(컨텍스트 요약), PostToolUse(편집 시 자동 재인덱싱), SessionEnd(자동 체크포인트) — 그리고 일반적인 작업을 위해 도구들을 조율하는 워크플로 스킬 세트를 연결합니다: explore, plan, review, debug, research, recall, catch-up, handoff, doc-gaps, scout, wiki.

플러그인 없이 스킬만 원하시나요? 스킬은 skills/ 아래에 있는 일반 SKILL.md 파일입니다. 원하는 것을 프로젝트의 .claude/skills/<name>/(리포지토리와 공유됨) 또는 ~/.claude/skills/<name>/(모든 프로젝트)에 복사하면 다음 세션에서 Claude Code가 인식합니다. 스킬은 Claude Code 기능이므로 다른 편집기에는 적용되지 않습니다 — 하지만 MCP 도구 자체는 어디서나 동작합니다.

검색 품질

89–97% Recall@10, 97–100% Recall@20, MRR 0.69–0.77. 세 가지 언어에 걸친 네 개의 실제 코드베이스에서 계층화되고 난이도가 혼합된 쿼리 세트(각각 72–120개, ~⅓은 어려움)로 벤치마킹했으며, 2026-06-04에 현재 파이프라인에서 재측정했습니다. 전체 방법론은 BENCHMARKS.md에 있습니다.

더 큰 리포지토리(Kubernetes, Excalidraw)는 올바른 파일 중 일부가 상위 10위 바로 밖에 랭크될 만큼 큽니다. 재현율은 상위 20위에서 97–100%에 도달하므로 큰 리포지토리에서는 searchTopK: 15–20으로 설정하세요.

코딩 에이전트 대비 (ContextBench)

또한 mimirs를 ContextBench(실제 리포지토리에서 골드 컨텍스트를 검색)에서 실행했습니다. 여기의 다른 항목들은 단일 호출 도구가 아니라 전체 코딩 에이전트 — 다단계 탐색기 — 입니다. 집중된 쿼리(LLM이 이슈를 읽은 후 보내는 쿼리)가 주어졌을 때, mimirs의 단일 검색 호출은 전체 에이전트 궤적과 비교해 다음과 같은 순위를 기록합니다:

mimirs는 단일 호출로 두 범위 지표 모두에서 선두입니다. 파일 정밀도가 마지막인 것은 의도적입니다: 골드 파일을 놓치면 치명적이고(LLM은 수정할 코드를 전혀 보지 못함), 추가 파일 참조는 걸러내는 비용이 낮기 때문입니다 — 따라서 mimirs는 재현율을 최대화하고 정밀도 판별은 모델이 수행하도록 합니다. 그리고 그 낮은 파일 정밀도는 대부분 지표의 산물입니다: mimirs가 반환하는 비-골드 파일의 ~**86%**는 노이즈가 아니라 수정과 연관된 관련 컨텍스트(호출자, 타입, 형제 구현)입니다 — 골드를 기준으로 측정하면 정밀도는 0.19, 관련성을 기준으로 하면 0.87입니다.

동일한 재현율, 비용은 극히 일부. grep 전용 에이전트(원시 이슈, 인덱스 없음, 수정 코드 엿보기 없음)와 동일한 15개 이슈를 로컬라이즈하는 정면 비교에서: mimirs는 LLM 토큰 0개, 단일 ~15ms 호출로 관련 클러스터를 제공합니다. 반면 에이전트는 수렴하기까지 이슈당 ~11.5회의 도구 호출(각각 LLM 단계)이 필요했으며 — 기본 파일에서 멈췄습니다. 다중 파일 수정에서는 에이전트가 골드 파일의 **22%**에 도달했고, mimirs는 그 단일 호출에서 **56%**에 도달했습니다 — 의존성 그래프가 이슈가 결코 언급하지 않는 2차 파일을 표면화합니다.

n=15 표본 대 에이전트의 500세트 — 방향성 있는 수치이며, 에이전트 도구 호출은 자체 보고된 값에 상한이 있습니다. 전체 리더보드, 주의사항, 관련성 및 비용 표는 BENCHMARKS.md에 있습니다.

비교

기존 도구를 사용하지 않는 이유는?

• Continue.dev의 @codebase — 가장 유사한 기능(로컬 RAG, 오픈소스)이지만, 검색은 편집기 확장 내부에 있습니다. Mimirs는 명시적인 도구(search, read_relevant, project_map, search_conversation, annotate)를 갖춰 에이전트가 계획을 세울 수 있는 독립형 MCP 서버이며, 대화 추적(tailing)과 위키 생성기도 내장되어 있습니다.

• Aider의 repo-map — 저장소의 정적 tree-sitter 요약이며, 임베딩이 없습니다. 영리하고 가볍지만, 요약은 검색이 아닙니다 — mimirs는 쿼리별로 벡터 + BM25로 청크를 순위화하고 그래프 중심성으로 가중치를 높입니다.

• Sourcegraph Cody / OpenCtx — 코드 검색에는 탁월하지만, 인덱싱이 클라우드 인프라와 계정에 의존합니다. Mimirs는 bunx 실행 한 번이면 되며, 코드가 컴퓨터를 떠나지 않습니다.

• llama-index / LangChain / 직접 구축 — 이것들은 라이브러리입니다. Mimirs는 배터리 포함(batteries-included) 방식입니다: AST 인지 청킹, 하이브리드 검색, 파일 감시, 대화 추적(tail), 주석이 이미 함께 연결되어 있습니다.

작동 방식

1. 파싱 및 청킹 — 콘텐츠를 유형에 맞는 전략으로 분할합니다: 코드는 함수/클래스 경계(24개 언어에 걸친 tree-sitter 사용), markdown은 헤딩, YAML/JSON은 최상위 키 기준. 임베딩 모델의 토큰 한도를 초과하는 청크는 윈도우 처리되어 병합됩니다.

2. 임베딩 — 각 청크는 all-MiniLM-L6-v2를 사용하여 384차원 벡터가 됩니다(Transformers.js + ONNX를 통한 인프로세스 방식, API 호출 없음). 벡터는 sqlite-vec에 저장됩니다.

3. 의존성 그래프 구축 — import 지정자와 내보낸 심볼은 AST 청킹 중에 캡처된 후 해석되어 파일 수준 의존성 그래프와 심볼 수준 호출 그래프를 구축합니다. impact는 함수의 전이적 호출자를 추적합니다(블래스트 반경 및 실행할 테스트). trace는 한 심볼이 다른 심볼에 도달하는 방법을 찾습니다. mimirs affected CLI는 git diff를 실행할 정확한 테스트 집합으로 변환합니다.

4. 하이브리드 검색 — 쿼리는 벡터 유사도와 BM25를 병렬로 실행하며, 상호 순위 융합(reciprocal-rank fusion, 가중치 기본 0.5)으로 결합됩니다 — 두 스코어러의 매우 다른 점수 척도에도 강건합니다. 식별자는 분할되므로(camelCase/snake_case) depends 검색이 getDependsOn과 일치합니다. 결과는 의존성 그래프 중심성과 경로 휴리스틱으로 가중치가 높아집니다. read_relevant는 엔터티 이름과 정확한 줄 범위(path:start-end)와 함께 개별 청크를 반환합니다.

5. 감시 및 재인덱싱 — 파일 변경은 2초 디바운스로 감지됩니다. 변경된 파일은 재인덱싱되고, 삭제된 파일은 제거됩니다.

6. 대화 및 체크포인트 — Claude Code의 JSONL 트랜스크립트를 실시간으로 추적합니다. 에이전트는 중요한 순간에 체크포인트를 생성하여 향후 세션이 검색할 수 있게 합니다.

7. 주석 — 파일이나 심볼에 첨부된 메모는 read_relevant 결과에 [NOTE] 블록으로 인라인 표시됩니다.

8. 분석 — 모든 쿼리가 기록됩니다. 분석 기능은 결과가 0개인 쿼리, 관련성이 낮은 쿼리, 기간 대비(period-over-period) 추세를 표시합니다.

데이터 처리

mimirs는 전적으로 사용자의 컴퓨터에서 실행됩니다. 저장소가 추적하는 파일과 추적되지 않지만 gitignore되지 않은 파일을 인덱싱합니다(따라서 gitignore하는 것을 잊은 .env가 읽힐 수 있습니다 — .env, *.pem, *.key, SSH 키 같은 일반적인 비밀 패턴은 기본적으로 제외됩니다. .mimirs/config.json의 exclude에 직접 추가할 수 있습니다). 파일 콘텐츠와 임베딩은 로컬 SQLite 파일인 <project>/.mimirs/index.db에 저장됩니다. 대화 인덱싱은 ~/.claude/projects/<this-project>/ 아래의 현재 프로젝트 트랜스크립트만 읽습니다.

유일한 네트워크 호출은 huggingface.co에서 임베딩 모델(Xenova/all-MiniLM-L6-v2)을 최초 1회 다운로드하는 것이며, ~/.cache/mimirs/models에 캐시됩니다. 코드는 절대 컴퓨터를 떠나지 않습니다 — 어떤 서버로도 전송되지 않습니다.

지원 언어

bun-chunk을 통한 tree-sitter 문법 기반 AST 인지 청킹:

TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Scala, Kotlin, Lua, Zig, Elixir, Haskell, OCaml, Dart, Bash/Zsh, TOML, YAML, HTML, CSS/SCSS/LESS

다음도 인덱싱합니다: Markdown, JSON, XML, SQL, GraphQL, Protobuf, Terraform, Dockerfiles, Makefiles 등. 알려진 확장자가 없는 파일은 단락 분할로 대체됩니다.

문서

• 예제 도구 출력 — 에이전트가 MCP를 통해 실제로 받는 내용

• MCP 도구, CLI 및 분석

• 설정 및 예제

• 벤치마크

스택

모든 데이터는 프로젝트 안의 .mimirs/에 저장됩니다 — .gitignore에 추가하세요.