Lore

소프트웨어 프로젝트를 위한 살아있는 지식 그래프.

상태: 1.0 이전, 1인 유지보수. Lore는 기능적으로 작동하며 실제 프로덕션 프로젝트에서 사용되고 있지만, API, 스키마 및 MCP 인터페이스는 마이너 버전 간에 변경될 수 있습니다. 버그 리포트는 환영하지만, 설계가 안정화될 때까지 기능 관련 PR은 병합되지 않을 수 있습니다. API가 안정화되면(목표: 1.0) 더 넓은 협업을 위해 저장소를 공개할 예정입니다.

Lore는 프로젝트의 비즈니스 로직(모듈, 기능, 흐름, 이벤트, 규칙, 폼, 엔티티 및 결정)을 SQLite 기반의 타입형 그래프로 캡처합니다. 이를 MCP를 통해 노출하여 AI 코딩 어시스턴트(Claude Code, Cursor, Claude Desktop)가 일반적인 작업의 일부로 이를 쿼리하고 유지 관리할 수 있도록 합니다.

이 도구는 "결제 등록 방법이 몇 가지나 존재하지?", "flow-checkout을 수정하면 무엇이 깨지지?" 또는 *"이 엔티티를 보호하는 규칙은 무엇이지?"*와 같은 질문에 대해 매번 코드베이스를 다시 탐색할 필요 없이, 출처와 함께 단일 도구 호출로 답변합니다.

왜 Lore인가?

• 세션 간 지속적인 메모리 — 컨텍스트가 초기화되어도 그래프는 유지됩니다.

• 문서화 오버헤드 제로 — 별도의 번거로운 작업이 아니라, 개념이 결정될 때 어시스턴트가 직접 기록합니다.

• 감사 가능(Auditable) — 모든 노드는 source, confidence, source_context를 포함합니다. 모든 MCP 호출은 기록됩니다.

• 토큰 효율성 — 요약 전용 목록, 배치 작업, 탐색을 위한 저비용 하위 에이전트, WAL 모드 SQLite를 지원합니다.

Related MCP server: kg-memory-mcp

설치 (Claude Code 플러그인 — 권장)

/plugin marketplace add YACB2/lore
/plugin install lore@lore

재시작 후, 모델링하려는 프로젝트에서 lore init을 실행합니다(또는 Haiku를 사용하여 코드를 스캔하는 가이드 온보딩을 위해 /lore:bootstrap 실행). "프로젝트"는 단일 저장소일 수도 있고 여러 저장소를 포함하는 워크스페이스일 수도 있습니다. Lore는 별도의 의견을 갖지 않으며, .lore/lore.db는 Claude Code를 실행한 디렉토리를 기준으로 생성됩니다.

플러그인 구성 요소:

• MCP 서버: lore_add_node, lore_add_nodes, lore_update_node, lore_delete_node, lore_get_node, lore_add_edge, lore_add_edges, lore_remove_edge, lore_query, lore_traverse, lore_list, lore_find_variants, lore_audit, lore_history, lore_stats, lore_export_markdown 노출.

• 자동 호출 스킬 (lore-usage): Claude가 행동하기 전에 읽고 결정 시 기록하도록 하며, 출처 규칙 및 수명 주기 관례를 따릅니다.

• 하위 에이전트 lore-explorer (Haiku, 읽기 전용): 비싼 토큰을 소모하지 않고 광범위한 탐색을 수행합니다.

• 슬래시 명령어: /lore:init, /lore:bootstrap, /lore:audit, /lore:show <id>, /lore:recent, /lore:impact <id>, /lore:probe <path> (디렉토리 전환 없이 다른 프로젝트의 그래프 감사).

설치 (독립형 CLI / 기타 MCP 호스트)

pipx install projectlore   # or: uv tool install projectlore
lore init

Cursor / Claude Desktop의 경우:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp", "--db", ".lore/lore.db"]
    }
  }
}

CLI 참조

lore init                      # create .lore/lore.db
lore list [--type flow]        # summary listing (id, type, title, status)
lore show <id>                 # full detail + edges
lore query "payment"           # exact id → title substring → tag fallback
lore variants <capability-id>  # flows implementing a capability
lore audit                     # orphans, cycles, id hygiene
lore stats [--since ISO]       # token/usage analytics from the audit log
lore export --out .lore/export # one markdown file per node

스키마

8가지 노드 타입 (스택 무관): module, capability, flow, event, rule, form, entity, decision.

9가지 관계: part_of, implements, depends_on, triggers, validates, enforces, supersedes, references, conflicts_with. 타입 쌍은 제한됩니다(schema.py 참조).

상태: active | draft | deprecated | superseded | archived. 소프트 삭제가 기본값이며, lore_delete_node는 오타 수정을 위해 예약되어 있으며 엣지 손실에 대해 경고합니다.

중심 추상화는 **capability**입니다. 이는 시스템이 수행하는 방법을 독립적으로 정의한 기능입니다. 여러 flow 노드가 동일한 기능을 implements하여 UX/로직의 차이를 드러낼 수 있습니다.

모델 라우팅

작업은 비용에 따라 분리됩니다:

• 읽기 (광범위한 스캔, 탐색, 감사): lore-explorer 하위 에이전트를 통해 Haiku에 위임하거나 슬래시 명령어의 model: haiku 프론트매터를 사용합니다.

• 쓰기 및 모델링 결정: 호출자의 모델(Sonnet/Opus). 하위 에이전트가 JSON을 제안하면 호출자가 검토하고 저장합니다.

프로젝트별 재정의는 .lore/config.json에서 수행합니다:

{
  "language": "es",
  "app_name": "my-app",
  "models": { "exploration": "haiku", "write": "sonnet" }
}

출처 및 기록

모든 노드는 metadata.{source, confidence, source_context}를 가지며, 관련이 있는 경우 source_ref (path:line), last_verified_at, deprecated_at, deprecated_reason, replaced_by를 포함합니다.

lore_update_node(metadata_patch=…)는 출처를 파괴하지 않고 병합합니다. 드문 경우의 전체 교체를 위해 metadata는 여전히 존재합니다.

lore_history(id)는 추가 전용 감사 로그에서 노드에 대한 모든 MCP 이벤트를 반환합니다(최신순). lore_stats는 도구/작업별로 집계하여 입력/출력 바이트를 보고합니다.

상태

Pre-MVP, 알파 단계입니다. 스키마와 MCP 도구 인터페이스는 0.1.0 이전에 변경될 수 있습니다.

개발

uv sync --all-groups
uv run pytest -q
uv run ruff check src tests

테스트는 tests/에 있습니다. 플러그인 레이아웃은 test_plugin_structure.py에 의해 검증됩니다.

라이선스

MIT.