Selvedge
AI가 작성한 코드베이스를 위한 장기 기억 — 이미 시도했고 기각된 것까지 포함해서.
라인 속성(Line attribution)은 누가 무엇을 작성했는지 알려줍니다. Selvedge는 에이전트에게 다음에 작성하지 말아야 할 것을 알려줍니다: 이 코드베이스가 이미 시도했고, 되돌렸으며, 그 이유까지. AI 에이전트를 위한 git blame — 어떤 모델이 어떤 라인을 건드렸는지가 아니라 왜 그랬는지를 위한 도구입니다. 변경이 일어나는 순간 에이전트가 직접 실시간으로 포착하므로, 이후의 어떤 작업도 그것을 추측할 필요가 없습니다.
Selvedge는 로컬 MCP 서버입니다. AI 코딩 에이전트(Claude Code, Cursor, Copilot)는 작업하면서 이를 호출해 추론과 함께 구조화된 변경 이벤트를 기록합니다. 데이터는 코드 옆의 .selvedge/ 디렉토리 아래 SQLite 파일에 안전하게 보관됩니다.
기본은 로컬 우선, 팀 서버는 선택, LLM은 항상 제로.
여섯 달 전, 당신의 AI 에이전트는 user_tier_v2라는 컬럼을 추가했습니다. 당신은 그 이유를 모릅니다. git blame은 "Update schema."라는 생성된 메시지가 담긴 claude-code의 커밋을 가리킵니다. 그 변경을 만든 세션은 이미 사라졌고 — 그 변경을 만들어낸 프롬프트도 마찬가지입니다.
Selvedge를 사용하면 대신 이렇게 실행합니다:
$ selvedge blame user_tier_v2
user_tier_v2
Changed 2025-10-14 09:31:02
Agent claude-code
Commit 3e7a991
Reasoning User asked to add a grandfathering flag for legacy free-tier
users during the pricing migration. Stores the original tier
so we can backfill discounts without touching billing history.그 추론은 에이전트가 그 순간에 포착한 것입니다 — 변경을 만들어낸 바로 그 컨텍스트에서 Selvedge에 기록된 것입니다. 나중에 두 번째 LLM이 diff에서 유추한 것이 아닙니다. 손으로 입력한 커밋 메시지도 아닙니다.
Selvedge는 누구를 위한 도구인가
Selvedge에는 두 가지 사용자가 있습니다. 같은 도구, 같은 pip install, .selvedge/ 아래의 같은 SQLite 파일. 고통의 규모만 다릅니다.
장기 운영되는 AI 코딩 코드베이스를 가진 팀.
프로젝트가 충분히 커서 당신(또는 다른 누군가)이 6개월 후, 12개월 후, 3년 후에 다시 만지게 될 때 — 하지만 대부분이 각 PR이 배송된 날 컨텍스트가 증발해버린 에이전트에 의해 작성된 경우. git blame은 무엇이 변경되었는지 알려줍니다. Selvedge는 왜인지 알려줍니다 — 에이전트 세션, 프롬프트 템플릿, 그것을 요청한 개발자, 모델 버전이 모두 사라진 후에도. 이것이 원래의 사용 사례입니다: 프로덕션 코드베이스, 스키마 결정, 마이그레이션, 인력 교체를 견디는 감사 추적이 필요한 의존성 변경.
일상적인 프로젝트에서 Claude Code를 사용하는 개인 개발자.
사이드 프로젝트, 주말 빌드, 계속 손보는 작은 내부 도구. 엔터프라이즈 거버넌스는 필요 없습니다 — 어제, 지난주, 지난 스프린트에 당신(또는 당신의 에이전트)이 왜 그런 일을 했는지 기억하기만 하면 됩니다. selvedge init을 한 번 실행하세요. CLAUDE.md에 네 줄을 추가하세요. 그 후로 selvedge blame은 근육 기억이 됩니다 — 과거의 자신이 LLM이었을 때, 그 과거의 자신과 대화하는 방법입니다.
당신이 직접 만든 AI 기반 프로젝트로 돌아와서 "이게 뭐 하려고 만든 거였지?"라고 생각해본 적이 있다면, Selvedge가 바로 그 빠진 조각입니다.
Related MCP server: claude-engram
문제
인간이 작성한 코드는 의도를 곳곳에 새어 나오게 합니다 — 커밋 메시지, PR 설명, 인라인 주석, 그 앞에 있던 Slack 스레드. AI가 작성한 코드는 그렇지 않습니다. 에이전트는 각 결정을 내린 이유에 대해 완벽한 명확성을 가지고 있지만, 그 컨텍스트는 프롬프트 안에 살다가 대화가 끝나면 증발합니다.
여섯 달 후, 당신의 팀은 흔적이 없는 스키마 결정을 디버깅하고 있습니다. git blame은 무엇이 언제 변경되었는지 알려줍니다. 왜인지는 알려줄 수 없습니다.
Selvedge는 왜를 포착합니다 — 변경이 이루어지는 순간, 에이전트 자신이 직접 실시간으로. diff는 git의 일입니다. 왜는 Selvedge의 일입니다.
v0.3.10의 새로운 기능
메모리가 에이전트에게 전달되고, 저장소에 다이얼이 생깁니다. 두 가지 테마가 함께 출시되었습니다. 설정 부분이 나머지가 설정을 읽는 데 필요했기 때문입니다.
전달(Delivery). Selvedge는 이미 되돌려진 엔티티의 재편집을 차단했습니다. 부족했던 것은 거부할 것이 없을 때의 전달이었습니다. 두 개의 새로운 훅:
SessionStart는 세션이 시작될 때 간결한 요약을 주입합니다 — 재검토가 필요한 결정, 시도했다가 되돌려진 엔티티, 최근 변경 세트.
PreCompact는 컨텍스트 압축이 이 세션의 추론을 파괴하기 직전에 실행되며, 편집했지만 기록하지 않은 감시 중인 엔티티를 명명합니다.
둘 다 말할 것이 없을 때는 조용하고, 크기가 제한되며, 읽기 전용이고, 템플릿 기반입니다. 둘 다 어떤 것도 차단할 수 없습니다 — PreCompact는 훅 API가 제공하는 거부 권한을 의도적으로 거절합니다. 이것은 측정된 실패 모드에 대한 답입니다: 2026년 논문 두 편이 풀 모델 메모리 도구가 완전히 사용되지 않는 것을 기록했습니다(사전 시드된 저장소에 대해 114턴 동안 자발적 메모리 작업 0회) 반면 결정적 주입은 매번 성공했습니다.
selvedge export --format markdown 은 저장소를 검토 가능한 요약으로 렌더링하여 옆에 커밋할 수 있게 하므로, 포착된 의도가 바이너리 안에 숨는 대신 풀 리퀘스트에 나타납니다. 결정적입니다 — 새 이벤트 없이 재생성하면 0줄 diff입니다.
설정(Config). .selvedge/config.toml이 이제 일급 시민이며, selvedge doctor가 설정별로 출력하는 표준 우선순위 체인이 있습니다. 제공하는 것:
selvedge prune --include-events— 포착된 추론을 삭제할 수 있는 첫 번째 경로이므로, 확인과SELVEDGE_DESTRUCTIVE=1둘 다 필요합니다. 둘 중 하나만으로는 충분하지 않습니다. cron 항목의--yes는 프롬프트를 무력화하고 셸 프로필은 환경 변수를 무력화하기 때문입니다. 이벤트 보존은 기본적으로 영구입니다.이벤트 크기 상한 (
diff_bytes,reasoning_bytes) — 텍스트의 마커, 쓰기 시점의 경고,selvedge stats의 카운트로 크게 알립니다.비밀 패턴 경고 —
log_change시점에,redaction_patterns로 확장 가능하며, 이미 저장된 것을 스캔하는doctor행도 포함합니다. 경고만 하고 거부하지는 않습니다.
또한: 검토 이슈 5건이 해결되었습니다. 강제 훅의 허용 경로가 40% 빨라졌고 (게이트 호출당 33.6 ms → 20.1 ms), SELVEDGE_HOOK_DISABLE=1이 마침내 문서화된 대로 건너뛰기로 되어 있던 import 이전에 단락됩니다; log_change는 이름 변경과 대체 시 revisit_after / constraint / stale_when을 더 이상 버리지 않습니다; CLI의 --json과 MCP 도구가 이제 동일한 구조를 반환합니다; Docker 이미지가 더 이상 유지관리자의 자체 데이터베이스를 포함하지 않습니다. 테스트 826 → 984.
v0.3.9.3의 새로운 기능
깨진 설치를 수정하고, 전체 코드 품질 패스를 완료합니다. mcp 2.0.0(2026-07-28 출시)이 mcp.server.fastmcp를 제거했는데, Selvedge는 상한 없이 mcp>=1.0.0을 선언했습니다 — 그래서 그 날짜 이후의 어떤 pip install selvedge도 2.0.0을 가져왔고 selvedge-server가 import에서 실패했습니다. 이 릴리스는 의존성을 고정합니다. 서버가 시작을 멈췄다면, 이것이 이유입니다 — 업그레이드하세요.
코드베이스에 9번의 독립적인 패스를 적용한 검토와 함께 출시되었으며, 각 발견 사항을 조치하기 전에 반증하려고 시도했습니다. 17건의 확인된 결함이 수정되었습니다. 실제로 눈치챘을 만한 것들:
강제 훅이 차단해서는 안 되는 것을 차단하던 문제. 추적된 파일 읽기 —
cat,git diff,pytest,ruff check— 가 차단되었고, 오류 메시지가 실행하라고 알려준 해결 방법이 같은 게이트에 의해 차단되어 CLI에서 빠져나갈 방법이 없었습니다. 두 가지 경로가 더 같은 잘못된 차단을 유발했습니다: 주석 처리된 SQL 라인이 실제 삭제로 간주되었고, "revert"라는 단어만 포함된 커밋 메시지가 그 커밋이 건드린 모든 파일을 되돌려진 것으로 표시했습니다.조회가 대규모에서 빨라졌습니다. 주요 엔티티 읽기가 모든 행을 스캔하고 있었습니다 — 100k 이벤트에서 7.4 ms → 0.35 ms로 측정되었고, 훅은 대규모 저장소에서 수 초가 걸리던 문제가 있었습니다.
selvedge setup이 더 이상CLAUDE.md의 일부를 삭제할 수 없고, 중단된 백업이 더 이상 마지막으로 유효한 백업을 파괴할 수 없으며, 두 개의 Selvedge 프로세스가 실행 중일 때 업그레이드해도 데이터베이스 손상처럼 보이는 오류로 더 이상 충돌하지 않습니다.
테스트는 739 → 826으로 증가했습니다. 스키마 변경도 도구 표면 변경도 없으므로, 0.3.9.x 사용자는 그대로 교체 가능합니다.
Selvedge가 위치하는 곳
AI 에이전트는 작업하면서 Selvedge를 호출합니다. Selvedge는 왜를 내구성 있고 쿼리 가능한 저장소에 포착하고 다시 내보냅니다 — Agent Trace 레코드로는 교차 도구 독자를 위해, Sentry/Datadog 스택 트레이스에 연결되는 관측성 메타데이터로는, SOC 2 및 EU AI Act 감사를 위한 규정 준수 산출물로.
Selvedge는 git(라인 수준의 무엇/언제), PR 검토 도구(검토 시점의 품질), 에이전트 관측성(LLM 호출 추적), 또는 일반적인 코드 호스트 AI 기능을 대체하지 않습니다. 그것들 사이에 위치합니다 — 다른 모든 것이 참조하는 출처-일급-시민 계층입니다.
Selvedge 비교
"AI 에이전트를 위한 git blame" 카테고리가 빠르게 성장하고 있습니다. Selvedge가 어디에 맞는지 — 그리고 의도적으로 어디에 맞지 않는지입니다.
Rejected paths | Reasoning source | Granularity | Mechanism | Grouping | Storage | |
Selvedge | 쿼리 가능 — | 변경 시점에 실시간 캡처 — 변경을 만든 동일한 컨텍스트에서 에이전트가 기록 | 엔티티 — DB 컬럼, 테이블, 환경 변수, 의존성, API 라우트, 함수 | MCP 서버 — 작업이 발생할 때 에이전트가 호출 | 체인지셋 — 여러 엔티티에 걸친 명명된 기능/태스크 슬러그 | SQLite, 제로 의존성 |
제거됨 — | 파생됨 — 코드 상태의 tree-sitter 정적 분석 + 커밋 게이트 결정 노트 | AST 노드 (18개 언어 + 12개 IaC) | MCP 서버 — 일회성 인덱스 + 커밋 시 인증서 | 호출 그래프 엣지 |
| |
없음 | 세션 종료 시 diff에서 Claude Haiku가 사후 추론 | 라인 | Claude Code 라이프사이클 훅 → 로컬 데몬 | 세션/태스크 | 디스크의 JSONL | |
없음 | ed25519 서명된 크로스 에이전트 출처 | 라인 | 에이전트별 편집기 훅 + git 훅 (커밋 시 서명) | 없음 | git refs의 서명된 트레이스 | |
없음 — | 턴마다 실시간 캡처된 프롬프트 영수증 | 라인 | 에이전트 라이프사이클 훅 + git post-commit 훅 | 없음 | Git notes + sessions 브랜치 | |
없음 | 귀속 메타데이터 | 라인 | 에이전트 호출 체크포인트 → 커밋 시 Git notes | 없음 | Git notes | |
없음 | 프롬프트 영수증 — 프롬프트, 비용, 도구; 명시된 근거 없음 | 라인 | 에이전트 라이프사이클 훅 + post-commit 훅 | 없음 | Git notes |
"거부된 경로"가 중요한 이유 — 복사할 수 없는 유일한 것. 비용이 많이 드는 실패는 컬럼이 왜 존재하는지 잊는 것이 아닙니다. 팀이 좋은 이유로 이미 제거한 것을 에이전트가 자신 있게 다시 구현하는 것입니다. 그 이유를 아는 모든 사람이 컨텍스트 윈도우를 떠난 지 6개월 후에 말이죠. 위의 라인 귀속 도구 중 어느 것도 거부된 경로를 표면화하지 않으며, 이것은 릴리스 하나로 해결할 수 있는 기능 격차가 아닙니다 — 라인 중심 저장소에는 시도 → 되돌림 → 재시도 주기를 거쳐 지속된 엔티티라는 개념이 없기 때문입니다. docs/demos/prior-attempts.md를 참조하세요.
결정론이 중요한 이유. Selvedge의 근거는 에이전트 자신의 의도로, 변경을 만든 동일한 컨텍스트 윈도우에서 작성됩니다. 저장 또는 검색 경로 어디에도 모델이 없으므로, 동일한 쿼리는 오늘과 2년 후, 모델 버전을 넘어서도 동일한 답을 반환합니다. 근거를 사후에 추론하는 도구는 원래 프롬프트를 본 적 없는 두 번째 LLM을 실행하는 것입니다: 그것이 생성하는 것은 의역이며, 다시 실행하면 동일한 변경에 대해 다른 범주를 생성할 수 있습니다. 한 Hacker News 댓글 작성자가 경쟁 접근 방식에 대해 말했듯이, "grep은 'oauth-library'를 거부했기 때문에 당신의 커밋을 찾지 못할 것입니다… 결정론적 강제가 없다면 말이죠" (0x457).
결정론만으로는 더 이상 차별점이 아닙니다 — OpenLore도 결정론적 네이티브이며 그렇게 명시합니다. 차별화하는 복합 요소는 추가 전용 증언(append-only testimony) 입니다: 에이전트가 직접 작성한 근거가, 거부가 정리 대상인 비활성 상태가 아니라 일급 레코드로 취급되는 저장소에 보관되는 것입니다.
"엔티티 수준"이 중요한 이유. 대부분의 도구는 라인을 귀속시킵니다. Selvedge는 실제로 검색하는 대상을 귀속시킵니다: users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe. git blame 이후의 첫 번째 질문은 보통 *"이 컬럼의 이력이 뭐지"*이지, *"users.py의 40–48행의 이력이 뭐지"*가 아닙니다.
"실시간 캡처"가 중요한 이유. 그 자체로는 차별점이 아닙니다 — 여기 있는 모든 도구가 어떤 형태로든 주장합니다 — 하지만 근거를 신뢰할 수 있게 만드는 메커니즘입니다. 변경이 발생한 순간, 그것을 만든 컨텍스트에서 작성하는 것이 설명을 환각할 두 번째 모델이 경로에 없는 이유입니다. 빈 reasoning 필드 자체가 정직한 신호입니다: 에이전트에게 근거가 없었다는 뜻입니다.
비교는 2026-08-05 기준; OpenLore v2.1.8 / 265★, 소스에서 검증됨. 수정 사항은 이슈로 환영합니다.
"체인지셋"이 중요한 이유. Stripe 결제 롤아웃은 users 테이블, 두 개의 새 환경 변수, 세 개의 새 API 라우트, 하나의 의존성, 그리고 코드베이스 전반의 네 개 함수에 영향을 미칩니다. 모든 이벤트에 changeset:add-stripe-billing 태그를 달면 나중에 전체 범위를 다시 가져올 수 있습니다 — 원래 PR이 한 달에 걸쳐 여덟 개의 작은 PR로 쪼개졌더라도 말이죠.
Selvedge ↔ Agent Trace. Agent Trace는 Cursor가 발행한 오픈 AI 코드 귀속 와이어 포맷입니다 (RFC, 2026년 1월). 원래 GitHub 홈은 2026년 8월에 404가 되었고 그 뒤의 멀티 벤더 모멘텀도 사라졌지만, 스펙과 스키마는 여전히 agent-trace.dev에서 v0.1.0으로 고정된 채 해석됩니다. v0.3.9부터 selvedge export --format agent-trace는 Agent Trace v0.1.0 레코드를 생성하고 selvedge import --format agent-trace는 이를 다시 읽습니다 — 파일/라인 AI 귀속을 위한 이식 가능하고 문서화된 교환 포맷으로, 각 레코드의 dev.selvedge 메타데이터에 근거와 엔티티 수준 출처가 담깁니다. 매핑은 docs/agent-trace-interop.md에 있습니다; Selvedge는 스키마를 벤더링하며 업스트림 프로젝트에 대한 런타임 의존성이 없습니다.
빠른 시작
Claude Code — 플러그인 설치 (권장)
Claude Code 내에서 두 개의 명령어만 실행하면 됩니다. 사전 pip install 불필요 — 플러그인이 uvx(또는 pipx)를 통해 서버 자체를 부트스트랩합니다:
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge이것이 에이전트가 접하는 전체 표면을 한 단계로 처리합니다:
MCP 서버 — 8개 도구 (
log_change,prior_attempts,blame,diff,history,changeset,search,stale_decisions);스킬 — 에이전트에게 언제 호출할지 알려줍니다 — 추적 중인 엔티티를 편집하기 전, 실질적인 변경 후;
PreToolUse 강제 훅 — 스키마/마이그레이션 편집은 이 세션에서
prior_attempts가 확인될 때까지 차단되며, 차단 메시지에 이전 근거가 포함됩니다;슬래시 명령어 —
/selvedge:status,/selvedge:blame <entity>,/selvedge:history,/selvedge:prior-attempts <entity>.
저장소(.selvedge/selvedge.db)는 첫 번째 로그 변경 시 자동 생성됩니다. 두 가지 선택적 확장은 CLI 측에 남습니다: 각 이벤트에 커밋 해시를 스탬프하는 post-commit 훅(selvedge install-hook), 그리고 — selvedge 명령어를 셸 PATH에 추가하려면 — pip install selvedge로, 런처는 이후 정확한 고정 버전을 위해 uvx보다 이를 우선합니다.
Claude Code용 플러그인 또는
selvedge setup? 하나만 선택하세요. 둘 다 MCP 서버를 연결하며, 둘 다 실행하면 두 번 등록됩니다. 플러그인이 더 가벼운 경로이고 자체 업데이트됩니다. 플러그인을 사용 중이고 post-commit 커밋 해시 스탬핑만 원한다면selvedge install-hook을 단독으로 실행하세요.
기타 모든 MCP 클라이언트 — selvedge setup
Cursor, Copilot, Windsurf, Codex CLI, Gemini CLI 등:
pip install selvedge
cd your-project
selvedge setup그게 전부입니다. selvedge setup은 대화형 마법사입니다: 보유한 AI 도구(Claude Code, Cursor, Copilot)를 감지하고, 각 도구의 설정에 MCP 항목을 작성하고, 표준 에이전트 지침 블록을 프로젝트의 프롬프트 파일(CLAUDE.md / .cursorrules / copilot-instructions.md)에 넣고, PreToolUse 강제 훅을 .claude/settings.json에 설치하고(Claude Code 전용 — prior_attempts가 확인될 때까지 스키마/마이그레이션 편집을 차단; --skip-enforcement-hook으로 거부 가능), selvedge init을 실행하고, post-commit 훅을 설치합니다. 수정되는 모든 파일은 디스크에 변경 사항이 도달하기 전에 옆에 .bak 파일이 생성됩니다. 재실행은 no-op입니다.
CI 부트스트랩 또는 devcontainer.json postCreateCommand용:
selvedge setup --non-interactive --yes연결 확인 — 같은 프로젝트에서 두 번째 터미널을 엽니다:
selvedge watchAI 도구에서 아무 변경이나 만드세요 — 컬럼 추가, 함수 이름 변경, 환경 변수 추가. selvedge watch는 에이전트가 log_change를 호출한 후 1초 이내에 새 이벤트를 출력해야 합니다. 아무것도 도착하지 않으면 selvedge doctor를 실행하여 어느 단계가 조용히 깨졌는지 알려주는 단일 명령 건강 검사를 받으세요.
이력 쿼리:
selvedge status # recent activity + missing-commit count
selvedge diff users # all changes to the users table
selvedge diff users.email # changes to a specific column
selvedge blame payments.amount # what changed last and why
selvedge history --since 30d # last 30 days of changes
selvedge history --since 15m # last 15 minutes ('m' = minutes)
selvedge changeset add-stripe-billing # all events for a feature/task
selvedge search "stripe" # full-text search
selvedge stats # log_change coverage report (per-agent)
selvedge import migrations/ # backfill from migration files
selvedge export --format csv # dump history to CSV마법사를 실행하고 싶지 않다면, 마법사가 자동화하는 네 가지 수동 단계:
1. 프로젝트에서 초기화
cd your-project
selvedge init2. MCP 서버 등록
Selvedge는 표준 stdio MCP 서버이므로 모든 MCP 클라이언트에서 작동합니다 — Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI 등. 클라이언트별 정확한 설정은 모든 MCP 클라이언트와 호환 을 참조하세요. Claude Code의 경우:
claude mcp add selvedge -- selvedge-server3. 에이전트에게 사용하도록 지시
selvedge prompt --install CLAUDE.md--install을 클라이언트가 읽는 프롬프트 파일로 지정하세요 — 블록 자체는 모든 클라이언트에서 동일합니다:
클라이언트 | 프롬프트 파일 |
Claude Code |
|
Codex CLI (및 기타 |
|
Cursor |
|
Gemini CLI |
|
이렇게 하면 표준 에이전트 지침 블록이 센티널 괄호(<!-- selvedge:start --> / <!-- selvedge:end -->)로 감싸져 설치되므로, 이후 --install 호출 시 파일의 다른 부분은 건드리지 않고 괄호로 묶인 영역만 업데이트합니다. 또는 파이프로 전달할 수도 있습니다:
selvedge prompt | tee -a CLAUDE.md복사해서 붙여넣는 것을 선호하시나요? 동일한 블록은 웹사이트에서 한 번의 클릭으로 확인할 수 있습니다: selvedge.sh/prompt-block — 복사 버튼과 에이전트가 이 블록을 어떻게 활용하는지에 대한 설명이 함께 제공됩니다.
4. post-commit 훅 설치
selvedge install-hook위저드가 실행하는 것과 동일한 네 단계입니다.
모든 MCP 클라이언트와 호환
Selvedge는 표준 stdio MCP 서버입니다 — 실행 명령은 selvedge-server이며, pip install selvedge로 PATH에 추가됩니다. MCP를 지원하는 모든 클라이언트가 실행할 수 있습니다. 원하는 클라이언트를 선택하세요:
claude mcp add selvedge -- selvedge-server또는 프로젝트 수준의 .mcp.json을 커밋하여 팀 전체가 사용할 수 있게 하세요:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}문서: https://code.claude.com/docs/en/mcp
.cursor/mcp.json(프로젝트) 또는 ~/.cursor/mcp.json(전역):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Cursor의 최신 스키마는 명시적 "type": "stdio"도 허용합니다. command만 있는 형식도 작동합니다(Cursor는 command에서 stdio를 유추합니다).
문서: https://cursor.com/docs/mcp
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Windsurf는 파일을 핫 리로드하므로 재시작이 필요 없습니다. 앱 내 Plugins → View raw config 버튼을 누르면 Cascade가 읽는 정확한 파일이 열립니다. 문서: https://docs.windsurf.com/windsurf/cascade/mcp
~/.codex/config.toml:
[mcp_servers.selvedge]
command = "selvedge-server"또는 codex mcp add selvedge -- selvedge-server를 실행하세요.
문서: https://developers.openai.com/codex/config-reference
~/.gemini/settings.json(또는 프로젝트별 .gemini/settings.json):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}또는 gemini mcp add -s user selvedge selvedge-server를 실행하세요.
문서: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
대부분의 클라이언트는 동일한 JSON 형식을 공유합니다 — 다음을 가리키도록 설정하세요:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}selvedge-server를 찾을 수 없는 경우 절대 경로를 사용하세요(which selvedge-server).
작동 방식
Selvedge는 MCP 서버로 실행됩니다. Claude Code와 같은 도구의 AI 에이전트는 작업하면서 Selvedge의 도구를 호출하여 구조화된 변경 이벤트를 로컬 SQLite 데이터베이스에 기록합니다.
각 이벤트는 다음을 기록합니다:
무엇이 변경되었는지(엔티티 경로, 변경 유형, diff)
언제(타임스탬프)
누가(에이전트, 세션 ID)
왜(추론 — 그 순간 에이전트의 컨텍스트에서 캡처)
어디서(git 커밋, 프로젝트)
diff는 git의 역할입니다. 왜는 Selvedge의 역할입니다.
Selvedge는 자신의 이력을 추적합니다
이 저장소는 Selvedge를 직접 사용합니다(dogfooding): .selvedge/selvedge.db가 커밋되어 있어, 새로 클론하면 Selvedge 자체의 why-이력이 함께 제공됩니다. 클론한 후 Selvedge의 어떤 부분이 왜 변경되었는지 물어보세요:
git clone https://github.com/masondelan/selvedge
cd selvedge
selvedge status # recent changes to Selvedge itself
selvedge search "telemetry" # why the opt-in heartbeat shipped
selvedge blame selvedge/semantic.py # why semantic search was added모든 이벤트는 Selvedge를 구축한 에이전트들이 기록한 것입니다 — 이 README가 여러분의 프로젝트에서 사용하도록 요청하는 것과 동일한 log_change 호출입니다.
엔티티 경로 규칙
users.email DB column (table.column)
users DB table
src/auth.py::login Function in a file (path::symbol)
src/auth.py File
api/v1/users API route
deps/stripe Dependency
env/STRIPE_SECRET_KEY Environment variable접두사 쿼리는 모든 곳에서 작동합니다: users는 users, users.email, users.created_at 및 users. 네임스페이스 아래의 다른 모든 엔티티를 반환합니다.
MCP 도구
MCP 서버로 연결되면 Selvedge는 다음을 제공합니다:
도구 | 설명 |
| 엔티티, diff, 추론과 함께 변경 이벤트를 기록합니다. |
| 엔티티 또는 엔티티 접두사의 이력으로, 각 행에 |
| 정확한 엔티티의 가장 최근 변경 + 컨텍스트, 그리고 파생된 결정 |
| 모든 엔티티에 걸친 필터링된 이력 |
| 명명된 기능/작업 슬러그 아래에 그룹화된 모든 이벤트 |
| 모든 이벤트에 대한 전체 텍스트 검색 |
| 엔티티에 대한 이전 변경 시도 + 추론된 결과(tried → reverted → re-opened) — 편집 전에 호출하세요. 선택적 |
| 재검토가 필요한 결정: |
CLI 참조
selvedge init [--path PATH] Initialize in project
selvedge status Recent activity summary
selvedge diff ENTITY [--limit N] Change history for entity
selvedge blame ENTITY Most recent change + context
selvedge history [--since SINCE] Browse all history
[--entity ENTITY]
[--project PROJECT]
[--changeset CS]
[--summarize]
[--limit N]
selvedge changeset [CHANGESET_ID] Show events in a changeset
[--list] or list all changesets
[--project NAME]
[--since SINCE]
selvedge search QUERY [--limit N] Full-text search
selvedge prior-attempts ENTITY Prior attempts + inferred outcome,
[--description T] with the tried → reverted →
[--all] re-opened trail + status line
[--window 7d] (--all widens recall)
[--fuzzy TEXT] add semantic matches (needs the
semantic extra; substring fallback)
selvedge supersede ENTITY Re-open a reverted decision —
--reasoning TEXT append-only, links the prior
[--constraint TEXT] reverted event (or --supersedes ID)
[--stale-when TEXT]
[--supersedes ID]
selvedge index [--model NAME] Build/update the optional semantic
[--json] embeddings index (selvedge[semantic])
selvedge stale [--entity ENTITY] Decisions due for a revisit: past
[--project NAME] revisit_after + still in use, or
[--agent NAME] stale_when matched by a later change
[--json] ("review suggested")
selvedge stats [--since SINCE] Tool call coverage report (per-tool, per-agent)
selvedge doctor [--json] Health check: DB path, schema, hook, MCP wiring
selvedge install-hook [--path PATH] Install git post-commit hook
[--window MIN] (default 60 minutes)
selvedge backfill-commit --hash HASH Backfill git_commit on recent events
[--window MIN] (default 60 minutes)
selvedge import PATH Import migrations (SQL / Alembic) or
[--format auto|sql| an Agent Trace file (agent-trace)
alembic|agent-trace]
[--from-git] or walk git history for reverts:
[--since REF|DATE] revert-message commits + deletions
[--project NAME] become change_type="revert" events
[--dry-run] (idempotent on commit + entity)
selvedge export [--format json|csv| Export history (agent-trace =
markdown|agent-trace] Agent Trace v0.1.0 records;
markdown = reviewable digest)
[--since SINCE]
[--entity ENTITY]
[--ndjson] agent-trace: one record per line
[--collapse-by-session] agent-trace: merge a session into one
[--output FILE]
selvedge log ENTITY CHANGE_TYPE Manually log a change
[--diff TEXT] CHANGE_TYPE: add, remove, modify,
[--reasoning TEXT] rename, retype, create, delete,
[--agent NAME] index_add, index_remove, migrate,
[--commit HASH] revert, supersede
[--project NAME]
[--changeset CS]
[--revisit-after WHEN] ISO date or offset (e.g. 90d)
[--rename-from OLD] OLD path when CHANGE_TYPE is 'rename'
[--constraint TEXT] the principle behind the decision
[--stale-when TEXT] what would invalidate it
[--supersedes ID] with CHANGE_TYPE 'supersede'
selvedge migrate-paths Re-canonicalize stored entity paths
[--apply] (dry-run by default; --apply writes)
[--json]모든 읽기 명령은 머신이 읽을 수 있는 출력을 위해 --json을 지원합니다.
--since의 상대 시간:
15m→ 지난 15분(m= 분)24h→ 지난 24시간7d→ 지난 7일5mo→ 지난 5개월(mo또는mon= 개월)1y→ 지난 1년
파싱할 수 없는 입력(예: --since yesterday)은 조용히 빈 결과를 반환하는 대신 명확한 오류와 함께 종료됩니다. ISO 8601 타임스탬프도 허용되며 UTC로 정규화됩니다.
구성
방법 | 형식 | 예시 |
환경 변수 |
| 세션별 재정의 |
프로젝트 초기화 |
| CWD에 |
전역 폴백 |
| 프로젝트 DB가 없으면 사용 |
훅 감시 글로브 |
|
|
프로젝트 설정 |
| 아래 키 목록 참조 — 보존 기간, 크기 제한, 마스킹 패턴 |
전역 설정 |
| 동일한 키; 둘 다 설정된 경우 프로젝트 파일이 우선합니다 |
훅 우회 |
| 셸에 대한 PreToolUse 강제 훅을 비활성화합니다 |
의미론적 추가 기능 |
|
|
.selvedge/config.toml
모든 키는 선택 사항이며, 파일이 없으면 아래 기본값을 의미합니다. 우선순위는 CLI 플래그 → 환경 변수 → 프로젝트 .selvedge/config.toml → 전역 ~/.selvedge/config.toml → 기본값 순입니다. SELVEDGE_DB는 유일한 예외로, 데이터베이스 해석에서 항상 우선합니다. 구성 파일이 해당 경로를 해석하여 찾아지기 때문입니다. selvedge doctor는 모든 설정에 대해 적용된 값과 그 값을 생성한 단계를 출력합니다.
retention_days_events = 0 # 0 = never delete events (the default)
retention_days_tool_calls = 90 # local telemetry retention
backup_keep_last = 7
diff_bytes = 65536 # truncate oversized diffs at log time
reasoning_bytes = 32768 # truncate oversized reasoning
db_size_warn_mb = 500 # doctor warns above this
stale_days = 0 # 0 = off
digest_max_bytes = 4096 # cap on the session-start digest
redaction_patterns = [] # extra secret shapes to warn about
[hook]
watch_globs = ["**/migrations/**", "db/**/*.sql"]모든 키에는 환경 변수 재정의도 있습니다(SELVEDGE_DIFF_BYTES, SELVEDGE_RETENTION_DAYS_EVENTS, …).
풀 리퀘스트에서 캡처된 의도 검토
.selvedge/selvedge.db는 SQLite 파일이므로 내부의 추론은 diff에 표시되지 않습니다. 옆에 Markdown 다이제스트를 내보내고 둘 다 커밋하세요:
selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/다이제스트는 엔티티별로 그룹화되며 번복된 결정이 먼저 표시됩니다. 또한 결정적(deterministic)입니다 — 새 이벤트 없이 재생성하면 변경 사항이 없는 diff가 생성되므로, 모두가 건너뛰는 노이즈가 되는 대신 검토 가능한 상태로 유지됩니다. 제목 앵커는 엔티티 경로에서 파생되므로 다이제스트가 커져도 링크가 계속 작동합니다. 코드와 같은 커밋에서 재생성하거나 pre-commit 훅에서 재생성하세요.
커버리지 확인
에이전트가 실제로 log_change를 얼마나 자주 호출하는지 궁금하신가요? 두 가지 확인 방법이 있습니다:
# Quick summary in the terminal
selvedge stats
# Cross-reference against git commits
python scripts/coverage_check.py --since 30d커버리지 스크립트는 git 로그를 Selvedge 이벤트와 비교하여 어떤 커밋에 변경 이벤트가 연결되어 있는지 보여줍니다. 커버리지가 낮으면 일반적으로 시스템 프롬프트를 강화해야 한다는 뜻입니다 — docs/fallbacks.md의 지침을 참조하세요.
CI에서 (GitHub Action)
동일한 검사가 Selvedge Coverage Check 복합 Action으로 제공되므로, 푸시할 때마다 에이전트 커버리지를 추적할 수 있고, 필요에 따라 커버리지가 떨어지면 빌드를 실패시킬 수도 있습니다:
# .github/workflows/selvedge-coverage.yml
name: Selvedge coverage
on: [push, pull_request]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history so commits can be matched
- uses: masondelan/selvedge@v0.3.10 # pin to a release tag (or @main for latest)
with:
since: 30d
fail-under: "0.5" # optional: fail below 50% coverage; omit to report only이 Action은 작업 요약에 커버리지 요약을 작성하고 coverage-ratio, covered, total을 단계 출력으로 노출합니다. 이 Action은 git 이력을 Selvedge 이벤트 로그와 교차 참조하므로, 러너에는 프로젝트의 .selvedge/selvedge.db(커밋하거나 이 단계 전에 복원)와 전체 git 이력(fetch-depth: 0)이 필요합니다. 입력: since, window, limit, fail-under, selvedge-version, python-version, working-directory, db-path.
기여
git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytest아키텍처 세부 사항과 단계별 로드맵은 CLAUDE.md를 참조하세요.
라이선스
MIT — LICENSE를 참조하세요.
Available Tools
8 toolsblameBlame an entityARead-onlyIdempotent
Most recent change to an entity — what changed, when, who, why.
Like git blame but for semantic entities (DB columns, functions, env
vars, dependencies) and AI agents. Also carries the derived decision
state: status (active / reverted / reopened) and
superseded_by (id of a later supersede overriding this change, or
""). If no history exists for the entity, returns {"error": "..."}
with protocol-level isError: false.
Inputs: entity_path (required). Returns: id, diff, agent, error, +17 more
changesetGet a changesetARead-onlyIdempotent
All events that share a changeset_id, oldest first.
Use to reconstruct the full scope of a feature or task across multiple
entities. If the changeset has no events, returns
[{"error": "..."}] so the caller can distinguish "unknown changeset"
from "empty history."
Inputs: changeset_id (required). Returns: result
diffDiff an entity's historyARead-onlyIdempotent
Get change history for a codebase entity, newest first.
Supports prefix matching — e.g. 'users' returns all events for the users
table and any users.* column. Each event carries a derived
superseded_by id ("" when nothing overrode it), so the
tried → reverted → re-opened trail reads straight off the history.
Inputs: entity_path (required), limit. Returns: result
historyBrowse historyARead-onlyIdempotent
Filtered change history across all entities, newest first.
Combine since, entity_path, project, and changeset_id to scope
the result. On unparseable since input the response is
[{"error": "..."}] so the caller sees the problem.
Inputs: limit, since, project, entity_path, +1 more. Returns: result
log_changeLog a code changeA
Record a change to a codebase entity.
Call this immediately after making any meaningful change. The event is
written to the local SQLite store and returned with its assigned id and
timestamp. If the reasoning fails the quality validator (empty, too
short, or a generic placeholder), or the entity_path doesn't match the
usual shape for its entity_type, the result includes a warnings
array — the event is still stored.
Renames: pass the new path in entity_path, set change_type="rename",
and pass the old path in rename_from. Selvedge then writes two events —
a rename on the old path and a create on the new path with
metadata.renamed_from set — so the entity's history follows it. Example:
log_change(
entity_path="src/auth/session.py::login", # new path
change_type="rename",
rename_from="src/auth.py::login", # old path
entity_type="function",
reasoning="Split auth.py into an auth/ package; login moved.",
)Rejections: when you consider an approach and decide against it WITHOUT
writing the change, record the verdict with change_type="reject" — the
abandoned path is a first-class event, and the next agent's
prior_attempts query finds it as a high-confidence ("exact") row
instead of re-deriving the dead end. Name what was rejected AND what was
chosen instead, and record the condition that would invalidate the
verdict. Example:
log_change(
entity_path="users.card_pan",
change_type="reject",
entity_type="column",
reasoning="Rejected storing raw card PANs on the user row — "
"went with provider tokens instead; PANs in our own "
"DB put us in PCI scope.",
stale_when="payment provider changed",
expires_when="entity:deps/stripe:changes",
)Use change_type="revert" for the sibling case — the change WAS written
and then rolled back (clearer than a plain remove).
Superseding a reverted decision: when a reverted change becomes correct
again (the constraint that killed it no longer holds), do NOT delete or
edit history — log with change_type="supersede" and the reason. The
new event links the prior revert (auto-resolved when supersedes is
empty) and every read surface then reports the trail
tried → reverted → re-opened. Never re-apply a reverted change without
superseding it first.
On validation failure (invalid change_type, missing entity_path,
rename_from set without change_type='rename', supersedes set without
change_type='supersede', a supersede with nothing to re-open, or an
expires_when outside the closed grammar) the result is
{"status": "error", "error": "..."} with no event written.
Inputs: change_type (required), entity_path (required), diff, agent, +12 more. Returns: id, error, status, warnings, +2 more
prior_attemptsPrior attempts on an entityARead-onlyIdempotent
Prior change attempts on an entity, each with an inferred outcome.
Call this BEFORE editing an entity. If the same change was tried before
and reverted, you get the prior reasoning and change_type plus an
inferred outcome — so you can change your plan instead of repeating a
rejected approach.
Each result is a change event plus the trail fields: outcome
("reverted" — a later removal on the path; "reopened" — closed but a
later supersede re-opened it; "rejected" — a standalone reject event
that closed no earlier attempt, surfaced as its own row whose reasoning
IS the record; "active"), confidence ("exact" — the attempt was closed
by an explicit revert/reject, or the row is a standalone rejection;
"proximity_high" / "proximity_low" — the add->remove window heuristic
for implicit removals), outcome_reasoning (WHY it was rejected),
superseded_by + supersede_reasoning (the re-open, when present), and
current_status — the entity's standing now. Treat "reverted" and
"rejected" as "don't repeat this without a supersede"; "reopened" means
the old verdict no longer stands. Together they read: tried → reverted →
re-opened. Templated and deterministic — no LLM call; pull-only.
Conservative by design — min_confidence defaults to "proximity_high",
so an empty list (nothing clearly tried-and-rejected) is the normal,
preferred answer over a speculative false positive; "exact" rows always
clear that default floor. Pass min_confidence="proximity_low" to widen
recall. Rows carry match_type ("exact" / "substring" / "fuzzy") and
similarity.
Inputs: fuzzy, limit, description, entity_path, +2 more. Returns: result
searchSearch eventsARead-onlyIdempotent
Full-text search across entity paths, diffs, reasoning, and agents.
Useful for questions like 'what changes were made for the billing feature?', 'which columns were added by cursor?', or 'show everything related to authentication'.
Inputs: query (required), limit. Returns: result
stale_decisionsStale decisions due for revisitARead-onlyIdempotent
Decisions due for a revisit — expired, past their date, or with a triggered stale condition.
Three deterministic rules. Expiry-based (flag="expired"): events whose
expires_when condition fired, evaluated from local state only —
date: against now, entity:PATH:changes against the event log,
library:NAME>=VERSION against installed dist metadata; the pattern
kind that fired is in expired_pattern. A library: condition whose
dependency isn't locally observable surfaces as flag="manual_review"
instead of a guess; manual:LABEL never auto-fires. Date-based
(flag="revisit_due"): events whose revisit_after has passed AND the
entity is still live (queried via blame/diff/prior_attempts after
the decision, or its changeset saw later activity) — pure age alone
never surfaces. Condition-based (flag="review_suggested"): events
whose stale_when text shares keywords with a LATER change event — the
named invalidation evidence may have happened. Surfacing only: nothing
is un-retired automatically; follow up with a supersede if the
condition really was triggered. A later supersede that re-opens the
candidate (explicit supersedes id, or the same id-less auto-link
prior_attempts uses) drops it from this list; a same-path sibling
the supersede did not target still surfaces.
Each result is the change event plus flag, revisit_due,
days_overdue, active_use_signals, matched_terms,
matched_event_id, expires_status, expired_pattern,
expires_detail, and a one-line stale_reason. Date-due rows first,
most-overdue leading; filter by entity_path, project, or agent.
Templated and deterministic; no LLM call, no network.
Inputs: agent, limit, project, entity_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct scopes: log_change is the only writer; diff is entity-scoped history, history is cross-entity, changeset groups by id, and search is full-text. The main ambiguity is diff vs. blame — blame returns only the newest event and adds a status field, but it is effectively the first row of diff, so an agent could reasonably pick either for 'what changed most recently.'
The naming mixes three conventions: git-style single-word verbs (diff, blame, search), bare nouns (history, changeset), and descriptive snake_case phrases (log_change, prior_attempts, stale_decisions). The styles are individually readable and the git-inspired cluster ties the read tools together, but there is no single predictable verb_noun pattern across the set.
Eight tools is well within the ideal 3-15 range and each tool earns its place in the change-logging domain: one writer, four retrieval views (per-entity, latest, global, changeset-grouped), one search, one pre-edit decision helper, and one maintenance/review tool. The count feels tightly scoped with no obvious redundancy or bloat.
The surface fully covers the domain's lifecycle: log_change handles all event types (including rename, reject, revert, and supersede), and the read side provides entity-scoped history, latest state, cross-entity filters, changeset reconstruction, full-text search, pre-edit attempt lookup, and stale-decision review. The append-only design intentionally omits update/delete, which the descriptions explicitly justify, so there are no real dead ends for the stated purpose.
Maintenance
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared, scoped, reviewable team memory for AI coding agents.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.MIT
- AlicenseBqualityBmaintenancePersistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.2116MIT
- AlicenseAqualityAmaintenanceLocal-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.19978 PyPI877MIT
- AlicenseNot gradedqualityDmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT