scar-tissue
Installs Git hooks and scans commit history to automatically capture git revert/reset events as dead-end records, letting the anti-memory database learn from rolled-back changes.
Wraps pytest runs to track consecutive test failures and detect when a crash-loop is resolved, automatically recording the failed approach and the safe pivot that fixed it.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scar-tissue check scar tissue for src/db.py before I refactor the connection pool"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ScarTissue:别再往 CLAUDE.md 里塞垃圾了——只记“死路”的 Anti-Memory MCP 插件
从 Stanford
Memorilla(arXiv:2610.21375) 的 16-Token 隐空间记忆压缩与 LoreKit HN 记忆碎片化大讨论出发,将“卷通用闲聊记忆准确率”重构为“多 Agent 研发项目的隐式避坑疫苗(Anti-Memory / Scar Tissue)”。
一、 为什么需要 ScarTissue?(痛点与两级跳推演)
文本文档记忆(
CLAUDE.md/MEMORY.md)的工程死穴:超过 200 行即遭截断或引发严重的指令注意力稀释(Instruction Dilution)。
混杂陈旧笔记会跨会话污染上下文;人工手写维护成本极高。
闭源 Coding Agent 的最大真实痛点——“在同一个坑里反复横跳”:
高强度使用 Claude Code / Cursor / Codex 的开发者最痛的不是“AI 记不住缩进风格”,而是昨天刚因为隐蔽的 NCCL 跨卡死锁、SQLite 并发锁死或 32K 序列掩码 OOM 撤回(
git revert)了一种改法,今天开新 Session,AI 又自信满满地把同样的死路重写了一遍。
从 Stanford
Memorilla到本地极速“记忆守门员(Memory Gatekeeper)”:Memorilla证明了将长历史编码为 16 个紧凑隐空间向量 可节省 108—2,000 倍 Token 并减少 18.6%—24.2% 的无效原地打转(Wandering),但原生 Soft Prompt 绑定特定开源权重(Qwen3-8B)且人类不可读不可删改。ScarTissue 的工程降维与破局:
双触发器零人工采集:通过极简 Git Hook(捕获
git revert/git reset)与单测连败追踪器(捕获 连续 3 次跑挂单测后终于修好 的 Crash-Loop Recovery),自动提炼{当时试图做的改动 + 触发的报错根因 + 最终证明不可行的死路 + 验证可行的替代正路}。16 维轻量隐空间特征守门员 + 人类可审计双写存储:将每条死路编码为 16 维归一化语义/结构向量(8 维故障机理通道 + 8 维局部敏感结构哈希通道),同时落地至
.scartissue/scars.db(SQLite WAL)与人类可直接增删的.scartissue/scars.jsonl。防“粉红大象效应(Anti-Pink-Elephant)”的 ≤50 字中英自适应红线警告编译器:在下次 Agent 准备修改同一模块/符号时,不塞入几万字历史,而是精准弹出一条 严格 ≤ 50 字 的对比式正向转向警告(中文:
⛔忌[去字面化死路]([根因])→用[安全正路];英文:⛔NO [de-anchored hazard]([cause])->USE [safe pivot]),剥离危险 API 原文字面量,彻底消除 LLM 因负向提示注意力聚焦反而照抄错误代码的“粉红大象效应”。
Related MCP server: memini
二、 架构全景与目录结构
scar-tissue/
├── .github/workflows/ci.yml # GitHub Actions CI (Python 3.10–3.12, wheel & npm 只读冒烟测试)
├── .gitignore # 过滤构建产物、缓存与本地 SQLite/连败状态
├── .npmignore # npm 打包过滤配置
├── README.md # 项目文档与一键挂载指南
├── LICENSE # Apache-2.0 完整开源许可证
├── pyproject.toml # Python 包与 CLI 入口配置 (scar-tissue / scar-tissue-mcp)
├── package.json # 支持 npx scar-tissue-mcp / scar-tissue 一键启动
├── bin/
│ └── scar-tissue.js # npx 跨平台轻量包装器 (支持 Python>=3.10 / uv --no-project 自动探测)
├── scar_tissue/
│ ├── __init__.py
│ ├── __main__.py # 支持 `python -m scar_tissue` 直接执行
│ ├── models.py # 核心数据契约:ScarRecord, ScarMatch, ScarCheckResponse
│ ├── encoder.py # 16 维 Memorilla 风格特征守门员 + 防粉红大象 <=50 字编译器
│ ├── store.py # SQLite (WAL) + JSONL 双向原子同步存储与混合检索器
│ ├── hooks.py # Git Revert/Reset 自动提取器 + 连续 3 次单测崩溃恢复捕获器
│ ├── server.py # ~150 行极简 MCP Server 入口 (record_dead_end & check_scar_tissue)
│ └── cli.py # 命令行工具:MCP 服务、Git Hook 挂载、真实测试运行与终端检索
├── benchmarks/
│ ├── evaluate_real_oss_commits.py # 5 个真实开源仓库 (MCP SDK/Servers, Pydantic-AI) Commit 实测脚本
│ └── evaluate_5_scenarios.py # 5 大经典高并发/OOM/死锁工程踩坑沙箱端到端复现脚本
├── reports/
│ └── SCAR_TISSUE_VALIDATION_REPORT.md # 10 大案例实测报告与防粉红大象消融对比
└── tests/ # 单元与端到端集成测试套件
├── test_encoder_and_limit.py
├── test_store_and_gatekeeper.py
├── test_git_and_pytest_hooks.py
└── test_mcp_server.py三、 快速开始与一键挂载(Claude Code / Cursor / Codex)
0. 环境前置条件(Prerequisites)
Python CLI / PyPI 模式:需要 Python >= 3.10(运行时依赖
mcp>=1.0.0,<2.0.0与pydantic>=2.0.0)。npx零配置模式:需要 Node.js >= 18,以及已安装scar-tissue依赖的 Python >= 3.10 环境 或 已安装uv(包装器会在无环境时自动通过只读缓存安全的uv run --no-project拉起)。
1. 安装与在 Claude Code / Cursor 中挂载 MCP Server
方式 A:通过 PyPI 安装(推荐)
pip install scar-tissue
scar-tissue --version方式 B:从 GitHub 克隆本地开发安装
git clone https://github.com/SnowyLumiere/scar-tissue.git
cd scar-tissue
pip install -e ".[dev]"
scar-tissue --version安装完成后,在项目的 .mcp.json 或 Cursor MCP 配置中添加:
{
"mcpServers": {
"scar-tissue": {
"command": "scar-tissue-mcp",
"args": []
}
}
}方式 C:通过 npx 启动(发布至 npm 后支持一键零配置挂载)
{
"mcpServers": {
"scar-tissue": {
"command": "npx",
"args": ["-y", "scar-tissue-mcp"]
}
}
}注:MCP Server 启动后会自动向上探测当前工作区所属的 Git 仓库根目录(
<git-root>/.scartissue),也可通过环境变量SCAR_TISSUE_DIR在服务端显式指定存储路径。
2. 一键挂载 Git 自动避坑钩子 & 扫描历史死路
# 在目标仓库挂载 post-commit / post-rewrite / post-checkout 自动捕获钩子
scar-tissue install-hooks --repo /path/to/your/repo
# 冷启动:扫描仓库最近 50 次提交中的 Revert / Rollback 自动建库
scar-tissue capture-git --repo /path/to/your/repo --scan 50
# 包装执行单测命令:当同一模块连续 3 次单测失败并在第 4 次修复通过时,自动提炼死路
scar-tissue test -- pytest -q3. 核心 MCP 工具契约
工具名 | 触发时机 | 输入参数 | 返回效果 |
|
|
| 自动生成 16 维隐空间指纹与严格 |
| Agent 准备修改任何文件或模块前强制调用 |
| 无关文件返回空(零上下文污染);命中雷区时精准弹出 |
四、 真实开源仓库 Commit 实测验证(零个人/公司信息,100% 公开可查验)
运行端到端基准测试(含 5 个公开开源仓库真实 Commit SHA 实测 + 5 个经典工程沙箱压测):
PYTHONPATH=. python3 benchmarks/evaluate_real_oss_commits.py
PYTHONPATH=. python3 benchmarks/evaluate_5_scenarios.py
pytest tests/ -vA. 5 个来自官方 MCP / Pydantic-AI 仓库的真实公开 Git Revert / 死锁修复案例
案例编号 | 开源仓库与真实 Commit SHA | 目标模块与符号 | 弹出的 ≤50 字高优红线警告 ( | 字数 | 压缩比 | 粉红大象风险 (Raw $\rightarrow$ Pivot) |
OSS-1 |
|
|
| 50 字 | 84.2x |
|
OSS-2 |
|
|
| 50 字 | 77.8x |
|
OSS-3 |
|
|
| 50 字 | 108.4x |
|
OSS-4 |
|
|
| 50 字 | 123.0x |
|
OSS-5 |
|
|
| 50 字 | 96.4x |
|
B. 5 个经典高强度研发“AI 反复横跳”基准场景压测
场景编号 | 目标模块与符号 | 捕获来源 | 16 维守门员匹配度 | 弹出的 ≤50 字高优红线警告 ( | 字数 | 单次压缩比 | 粉红大象风险 (Raw -> Pivot) |
S1 |
|
|
|
| 48 字 | 13.9x |
|
S2 |
|
|
|
| 47 字 | 58.0x |
|
S3 |
|
|
|
| 49 字 | 35.3x |
|
S4 |
|
|
|
| 50 字 | 67.5x |
|
S5 |
|
|
|
| 50 字 | 30.1x |
|
历史雷区拦截召回率:10 / 10 (100%)
跨模块无关文件误报率:0 / 3 (0% 误报,零日常窗口污染)
单次命中平均压缩比:真实开源仓库案例(表 A)98.0x;合成 5 场景沙箱(表 B)单次平均 41.0x(模拟 8 轮会话累计对比全量历史 Token 节省估算约 1,640.3x)
粉红大象效应(字面禁用标识符泄漏风险):从传统反面警告的
1.00降至0.00
Available Tools
2 toolscheck_scar_tissueA
Mandatory pre-edit Gatekeeper: Check historical dead ends before modifying target_file.
Instead of dumping thousands of lines of CLAUDE.md history into the context window, returns strictly <= 50-char high-priority redline alerts ONLY when the target file, symbol, or 16-dim semantic intent matches a historical minefield.
Inputs: target_file (required), top_k, threshold, target_symbol, +1 more. Returns: result
record_dead_endC
Record a proven dead-end code change (Anti-Memory / Scar Tissue).
Extracts {attempted_change + error_root_cause + dead_end_approach + safe_pivot}, encodes a 16-dimensional latent scar vector (Memorilla-inspired gatekeeper), and compiles a strictly <= 50 character Contrastive Pivot redline alert.
Inputs: target_file (required), attempted_change (required), error_root_cause (required), dead_end_approach (required), +5 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are clearly distinct: record_dead_end writes a new scar, while check_scar_tissue reads historical scars. There is no overlap or ambiguity in their purposes.
Both names follow a consistent snake_case verb_noun pattern (record_dead_end, check_scar_tissue), making the set predictable and easy to parse.
Two tools is thin for a memory system; while record and check cover the core loop, additional operations like listing or deleting scars would be expected for a robust surface.
Core create and query operations exist, but there is no way to list, update, or delete recorded dead ends, leaving notable management gaps that could cause dead ends to become unmanageable.
Maintenance
Related MCP Connectors
Long-term, rotatable project memory and pre-write checks for AI coding agents.
Shared project memory for coding agents: decisions, lessons, guardrails and tasks per repository.
Shared debugging memory for AI coding agents
Shared memory for AI agents: search and record errors, fixes, gotchas and dead ends.
Related MCP Servers
- 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
- AlicenseAqualityDmaintenanceLocal-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.659 npmMIT
- AlicenseAqualityBmaintenanceHelps AI agents avoid repeating known failures by providing deterministic lookup of dead ends for coding errors and country-specific real-world rules.1118 PyPIMIT

DAiMONofficial
AlicenseNot gradedqualityCmaintenanceEnables AI assistants to check proposed actions against a local ledger of previously ruled-out work, receiving graded alerts with prior verdicts to avoid repeating dead ends.AGPL 3.0