وقتی از Cursor، Antigravity یا هر Agent کدنویسی دیگری می‌خواهید «این تابع را چه کسی صدا می‌زند؟» یا «اگر این API را عوض کنم چه چیزهایی می‌شکنند؟»، معمولاً Agent ده‌ها بار grep، glob و read file اجرا می‌کند. هر بار هزاران توکن context پر می‌شود و هنوز هم ممکن است زنجیرهٔ واقعی call chain یا edge بین سرویس‌ها دیده نشود.

codebase-memory-mcp دقیقاً برای همین ساخته شده: یک سرور MCP که کدبیس را با tree-sitter (۱۶۲ زبان) و Hybrid LSP به گراف دانش پایدار تبدیل می‌کند — توابع، کلاس‌ها، importها، مسیر HTTP، call chain و حتی لینک cross-service. Agent شما به‌جای «جستجوی کور در فایل‌ها»، کوئری ساختاری می‌زند.

تفاوت مهم: این ابزار LLM داخلی ندارد. هوش ترجمهٔ سؤال به کوئری، همان Agentی است که الان با آن صحبت می‌کنید (Cursor، Antigravity/Gemini و …). CBM فقط موتور تحلیل ساختاری است.

مشکل واقعی: Agent بدون حافظهٔ ساختاری

طبق preprint پروژه روی arXiv، روی ۳۱ ریپوی واقعی: کیفیت پاسخ ۸۳٪، ۱۰× توکن کمتر، ۲.۱× tool call کمتر نسبت به کاوش فایل‌به‌فایل.

معماری: از سورس تا گراف

سورس کد (162 زبان)
    ↓ tree-sitter AST + Hybrid LSP (Python, TS/JS, Go, Rust, Java, …)
گراف SQLite در حافظه (RAM-first، LZ4)
    ↓ dump یک‌باره
~/.cache/codebase-memory-mcp/  (+ اختیاری: .codebase-memory/graph.db.zst در git)
    ↓ 15 ابزار MCP
Cursor / Antigravity / Claude Code / …

نکات فنی:

• RAM-first pipeline: ایندکس در حافظه انجام می‌شود؛ SQLite در پایان dump می‌شود و RAM آزاد می‌شود.
• Hybrid LSP: برای زبان‌های اصلی، type resolution سبک (الهام‌گرفته از tsserver، pyright، gopls و …) دقت call graph را بالا می‌برد.
• Daemon هماهنگ‌کننده: یک daemon مشترک per-account برای watcher، UI و indexing پس‌زمینه — چند session Agent همزمان یک نسخهٔ binary را share می‌کنند.
• ۱۰۰٪ local: کد شما از ماشین خارج نمی‌شود؛ telemetry جمع نمی‌شود.

نصب سریع

macOS / Linux (توصیه‌شده)

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

اسکریپت:

1. باینری native مناسب پلتفرم را دانلود و verify می‌کند
2. Agentهای نصب‌شده (Cursor، Antigravity، Claude Code و …) را خودکار detect می‌کند
3. فایل MCP، Skill و agent/subagent مربوطه را می‌نویسد

Windows (PowerShell)

Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1

سایر روش‌ها

• npm: npm install -g codebase-memory-mcp
• pip: pip install codebase-memory-mcp
• Homebrew، Scoop، Winget، AUR

بعد از نصب Agent را restart کنید و بگویید:

«Index this project»

یا از tool index_repository استفاده کنید.

auto-index (اختیاری)

codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000

با فعال بودن auto_index، اولین اتصال MCP به پروژهٔ جدید، ایندکس را خودکار شروع می‌کند. watcher هم با git تغییرات را دنبال می‌کند (auto_watch پیش‌فرض true).

پیکربندی در Cursor

نصب خودکار، Cursor را در .cursor/mcp.json (پروژه) یا مسیر global تنظیم می‌کند. نمونهٔ دستی:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

آنچه installer برای Cursor می‌سازد:

نکتهٔ مهم Cursor: به‌دلیل race در session injection و محدودیت read-only subagent در MCP، context hooks در Cursor نصب نمی‌شوند. یعنی Agent والد باید خودش از MCP استفاده کند؛ subagentها evidence را از parent می‌گیرند (parent-handoff).

گام‌به‌گام در Cursor

1. نصب با install.sh یا دستی mcp.json
2. Restart Cursor
3. در Settings → MCP بررسی کنید codebase-memory-mcp با ۱۵ tool دیده شود
4. پروژه را باز کنید و بگویید: «این پروژه را index کن»
5. برای کاوش ساختاری از promptهای زیر استفاده کنید

Promptهای کاربردی:

چه کسی تابع processOrder را صدا می‌زند؟ از trace_path استفاده کن.

ساختار معماری این پروژه را با get_architecture خلاصه کن.

فایل‌های تغییرکرده در git چه symbolهایی را تحت تأثیر قرار می‌دهند؟ detect_changes بزن.

تابع‌های بدون caller (dead code) را پیدا کن، entry pointها را exclude کن.

سه tier کاوش (Scout / Verify / Auditor)

Installer سه پروفایل subagent می‌سازد:

در Cursor، subagent مستقیم به MCP دسترسی ندارد؛ والد باید نتیجهٔ search_graph، trace_path و check_index_coverage را در context delegation بگذارد.

پیکربندی در Antigravity (Google)

Antigravity از اکوسistem Gemini CLI استفاده می‌کند. installer این مسیرها را تنظیم می‌کند:

نمونهٔ دستی mcp_config.json:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

گام‌به‌گام در Antigravity

1. install.sh را اجرا کنید (Antigravity را detect می‌کند)
2. Antigravity / Gemini CLI را restart کنید
3. پروژه را باز کنید
4. در chat بگویید: «Index this repository with codebase-memory»
5. برای trace: «Show inbound callers of UserService.create using codebase-memory MCP»

Antigravity مثل Gemini CLI از GEMINI.md برای یادآوری workflow گراف در sessionهای تازه استفاده می‌کند. subagentهای Gemini (Scout/Verify/Auditor) در نسخه‌های پشتیبانی‌شده با tool list محدود ثبت می‌شوند.

۱۵ ابزار MCP — مرجع سریع

Indexing

Query & Analysis

ماتریس تصمیم سریع

Workflow عملی: از صفر تا refactor امن

۱. ایندکس

Agent: index_repository(repo_path="/path/to/my-app")

یا در CLI:

codebase-memory-mcp cli index_repository --repo-path /path/to/my-app
codebase-memory-mcp cli list_projects

۲. کشف symbol

codebase-memory-mcp cli search_graph \
  --project my-app \
  --name-pattern '.*Handler.*' \
  --label Function

۳. trace

codebase-memory-mcp cli trace_path \
  --project my-app \
  --function-name ProcessOrder \
  --direction both \
  --depth 3

۴. Cypher (مثال dead code)

MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
RETURN f.name, f.file_path
LIMIT 20

۵. قبل از refactor

detect_changes() → symbolهای affected → trace_path روی هر کدام → check_index_coverage

UI گراف سه‌بعدی

هر install شامل UI داخلی است:

codebase-memory-mcp --ui=true --port=9749

مرورگر: http://localhost:9749

• explore بصری nodes/edges
• multi-repo «galaxy» layout
• daemon مشترک — session دوم UI duplicate راه نمی‌اندازد

اگر دستی اجرا می‌کنید و process فوراً exit شد: stdin بسته شده (رفتار MCP). برای تست: sleep infinity | codebase-memory-mcp --ui=true --port=9749

اشتراک گراف در تیم (Team Artifact)

می‌توانید .codebase-memory/graph.db.zst را commit کنید:

• teammate با clone + اولین index_repository فقط incremental diff را می‌زند
• .gitattributes با merge=ours خودکار ساخته می‌شود — conflict روی binary کم
• اگر نمی‌خواهید: .codebase-memory/ را در .gitignore بگذارید

امنیت و حریم خصوصی

• پردازش ۱۰۰٪ local — سورس و query از ماشین خارج نمی‌شود
• installer فایل config Agent را می‌نویسد؛ سورس کامل برای audit در دسترس است
• releaseها از VirusTotal رد می‌شوند؛ Microsoft Defender گاهی false positive Wacatac.B!ml می‌دهد
• برای deployment چندمستأجره: CBM_ALLOWED_ROOT مسیر index را محدود می‌کند

Troubleshooting

Diagnostics حافظه:

export CBM_DIAGNOSTICS=1
# reproduce issue → فایل trajectory.ndjson در لاگ daemon

مقایسه با grep معمولی Agent

Agent بدون CBM:

grep "ProcessOrder" → 47 فایل
read 12 فایل → 80K tokens
هنوز caller در package دیگر miss شده

Agent با CBM:

search_graph(name_pattern="ProcessOrder")
trace_path(function_name="ProcessOrder", direction="inbound", depth=3)
→ ~500 tokens، کل chain ساختاری

برای پروژه‌های بزرگ (monorepo، microservice، کد legacy) این تفاوت بین «حدس Agent» و «refactor امن» است.

جمع‌بندی

codebase-memory-mcp لایهٔ حافظهٔ ساختاری را به Agent کدنویسی اضافه می‌کند:

1. نصب یک‌خطی — Cursor و Antigravity auto-config
2. ایندکس سریع — میلی‌ثانیه تا چند دقیقه بسته به اندازه
3. ۱۵ tool MCP — trace، architecture، impact، Cypher، ADR
4. توکن drastically کمتر — Agent هوشمندتر با context کوچک‌تر
5. local & private — بدون API key، بدون ارسال کد

قدم بعدی

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Cursor یا Antigravity را restart کنید، پروژه را باز کنید، و بگویید:

«این پروژه را index کن و بگو entry pointهای HTTP کجا تعریف شده‌اند.»

منابع:

• GitHub — DeusData/codebase-memory-mcp
• Paper — arXiv:2603.27277
• Cursor MCP Docs
• Model Context Protocol

این مقاله در P30Light منتشر شده — بخش هوش مصنوعی و ابزارهای توسعه.