CodeSmriti-永久内存MCP系统

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.11+](https://www.python.org/downloads/) ](https://www.docker.com/)

*Smriti：梵语，意为“记忆、回忆、被记住的东西”*

一个持久的知识库系统，可以智能地索引、组织和检索来自约100个GitHub存储库的代码和文档。基于模型上下文协议（MCP）构建，可与AI助手无缝集成。

问题

多年来，您的团队在数十个存储库中构建了令人难以置信的解决方案，但是：

🔍 “我们以前不是解决过这个问题吗？” -工程师们浪费数天时间重新实现某个地方已经存在的功能
📚 知识孤岛 -最佳实践和架构决策被困在旧的PR、Slack线程或离职的工程师头脑中
🔄 重新发明轮子 -每个新项目都是从头开始，而不是利用经过验证的模式
🤔 登机疼痛 -新工程师花数周时间了解“我们在这里是如何做事的”
💭 上下文丢失 -“为什么我们选择智威汤逊而不是会议？”-没有人记得，推理埋在某个地方

成本浪费的工程时间，不一致的实现，以及当人们离开时消失的知识。

解决方案

CodeSmriti是您团队的“Pensieve”——一个永远的记忆系统，它：

📚 摄入所有代码存储库和文档都是自动生成的
🧠 理解使用向量嵌入（而不仅仅是关键字匹配）进行语义编码
🏷️ 组织基于LLM的标签和人工输入的内容
🔍 检索立即实现类似的实现和最佳实践
🔗 整合通过MCP协议与您的AI助手
💡 保留跨团队变革的机构知识

询问CodeSmriti：

“告诉我我们是如何在我们的服务中实施限速的”
“查找有关身份验证的所有架构决策”
“我们处理错误的最佳实践是什么？”
“我需要构建一个重试机制-向我展示类似的代码”

⚡ V4架构（2025年11月）

CodeSmriti V4推出 分层文档索引 随着 LLM生成的摘要:

✅ 层级结构 -回购→ 模块→ file → 符号（自下而上聚合）
✅ 法学硕士概述 -每个文档都有语义摘要，以便更好地搜索
✅ 无原始代码存储 -仅在索引中进行总结；通过API按需获取代码
✅ 本地嵌入 - nomic-embed-text （768d）采用Apple Silicon MPS加速
✅ 多级搜索 -以符号、文件、模块或仓库粒度进行查询

生产统计数据（101回购）：

48795个索引文档（13K个文件，31K个符号，4K个模块）
每个文件约1850个令牌用于LLM富集
总摄入时间为32小时（平均约20分钟/次）

📖 V4架构规范 | V4摄入指南

运作原理

数据流（V4）

┌─────────────────────────────────────────────────────────────────┐
│                      1. PARSE & EXTRACT                         │
│  GitHub Repos → Clone → tree-sitter → Symbols (functions/classes)│
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│                    2. LLM ENRICHMENT                            │
│  Symbols → LLM Summary → Files → Modules → Repo (bottom-up)    │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│                      3. EMBEDDING                               │
│  Summaries → nomic-embed-text (768d) → Vector Embeddings       │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│                      4. STORAGE                                 │
│  Couchbase: {summary, embedding, metadata, hierarchy links}    │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│                    5. RETRIEVAL                                 │
│  Query → Embed → Vector Search (symbol/file/module/repo level) │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│                   6. AI INTEGRATION                             │
│  MCP Tools → Claude Code → Navigate hierarchy → Fetch code     │
└─────────────────────────────────────────────────────────────────┘

逐步过程（V4）

1.解析和提取

将存储库克隆到本地存储
树状图将代码解析为符号（函数、类、方法）
提取导入、文档字符串和结构元数据
符号>=5行得到自己的可搜索文档

2.LLM强化（自下而上）

LLM根据代码+文档字符串为每个符号生成摘要
从符号摘要聚合文件摘要
从文件摘要聚合模块（文件夹）摘要
存储库摘要聚合了模块摘要

3.嵌入生成

每个摘要都嵌入为768维向量
用途 nomic-embed-text 苹果Silicon MPS加速
嵌入捕获语义意义以进行相似性搜索

4.分层存储

Couchbase存储4种文档类型： repo_summary, module_summary, file_index, symbol_index
每个文档都有：摘要、嵌入、元数据、父/子链接
未存储原始代码-通过按需获取 get_file API

5.多级检索

在任何级别搜索：符号（特定）、文件、模块或仓库（广泛）
向量搜索找到语义相似的摘要
导航层次结构：从仓库向下钻取→ 模块→ file → 符号
仅在需要时获取实际代码

6.人工智能集成

MCP工具： list_repos, explore_structure, search_codebase, get_file, ask_codebase
Claude Code智能地导航层次结构
渐进式披露：先概述，再深入细节

示例查询流（V4）

You: "How does authentication work in labcore?"

1. search_codebase("authentication", level="module")
   → Finds: associates/ module - "Handles user auth, permissions, guardian integration"

2. explore_structure("kbhalerao/labcore", "associates/")
   → Shows: models.py, views.py, backends.py, permissions.py

3. search_codebase("login flow", level="symbol", repo="kbhalerao/labcore")
   → Finds: LoginView class (views.py:45-120), authenticate() (backends.py:15-45)

4. get_file("kbhalerao/labcore", "associates/backends.py", 15, 45)
   → Returns actual code for the authenticate function

Result: Progressive disclosure from high-level overview to specific implementation

关键能力

语义搜索

按含义查找代码，而不仅仅是关键字
“authentication”匹配“login”、“auth”、“verify user”

上下文元数据

知道是谁写的，何时写的，为什么写的（来自提交消息）
查看代码如何随时间演变

跨存储库模式

了解不同团队如何解决类似问题
识别不一致和标准化机会

机构记忆

用标签标记决策： #architecture-decision, #best-practices
永远不要失去选择背后的“为什么”

AI原生集成

与Claude Desktop、VSCode或任何MCP客户端无缝协作
代理工作流程：人工智能可以迭代地探索和综合发现

建筑

内部架构

┌─────────────┐         ┌──────────────┐         ┌────────────────┐
│   Ollama    │◄────────│  MCP Server  │◄────────│  API Gateway   │
│  (Native)   │         │  (Docker)    │         │    (Nginx)     │
└─────────────┘         └──────┬───────┘         └────────────────┘
                                │
                        ┌───────┴───────┐
                        │               │
                   ┌────▼─────┐   ┌────▼──────────┐
                   │ Couchbase │   │   Ingestion   │
                   │  Vector   │   │    Worker     │
                   │  Database │   │   (Docker)    │
                   └───────────┘   └───────────────┘

外部访问（生产）

Internet
   │
   ▼
┌──────────────────────────────────────────────┐
│   External Nginx (SSL Termination)           │
│   - Domain routing (codesmriti.domain.com)   │
│   - Let's Encrypt SSL certificates           │
│   - Cloudflare proxy (optional)              │
└───────────────┬──────────────────────────────┘
                │ HTTP (port 80)
                ▼
┌──────────────────────────────────────────────┐
│   CodeSmriti Internal Nginx                  │
│   - No SSL needed (behind external proxy)    │
│   - Routes to MCP Server                     │
└───────────────┬──────────────────────────────┘
                │
                ▼
        MCP Server (port 8080)

组件：

MCP服务器：基于FastAPI的MCP服务器，支持HTTP/SSE传输
Couchbase 的：统一文档+矢量存储
奥拉玛：在Mac M3 Ultra上本机运行的本地LLM
摄入工人：用于解析和索引存储库的后台服务
Nginx内部：用于路由的API网关（无SSL）
外部Nginx：SSL终止和基于域的路由

技术栈

MCP框架：Python+FastAPI
矢量数据库：带矢量搜索的Couchbase 8.0
嵌入: nomic-embed-text-v1.5 （768维，MPS加速）
LLM强化：LM Studio或Ollama（qwen2.5编码器、codellama、deepseek编码器）
代码解析：树保姆（Python、JavaScript/TypeScript、Go、Rust、Java）
认证：带API密钥的JWT
文档架构：V4分层（repo→ 模块→ file → 符号）

部署选项

选项1：外部Nginx反向代理（推荐用于生产环境）

如果你有一个单独的nginx网关来处理SSL和域路由：

在您的外部nginx服务器上，添加此上游配置：

upstream codesmriti {
    server internal-server-ip:80;  # CodeSmriti machine IP
}

server {
    listen 443 ssl http2;
    server_name codesmriti.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://codesmriti;
        proxy_http_version 1.1;

        # WebSocket/SSE support for MCP
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Long timeouts for MCP operations
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }
}

在您的CodeSmriti计算机上，只需运行：

docker-compose up -d

CodeSmriti上不需要SSL配置-外部nginx会处理它。

选项2：使用SSL直接访问互联网

如果CodeSmriti直接暴露在互联网上，请参阅 SSL-SETUP.md 用于使用Certbot和Cloudflare配置SSL。

快速开始

全新M3 Mac安装（自动）

对于具有GUI访问权限的本地Mac：

cd code-smriti
./quick-install.sh

对于通过SSH（无GUI）的远程Mac：

cd code-smriti
./quick-install-headless.sh    # Uses Colima instead of Docker Desktop

这两个脚本都会自动处理所有内容：

安装Homebrew、Docker/Colima和Ollama
下载AI模型（~15GB）
配置环境
启动所有服务
初始化数据库

预计时间：30-60分钟

看 安装.md 有关详细的安装说明和手动设置步骤。

快速手动设置（如果已安装依赖项）

如果你已经安装了Docker和Ollama：

# 1. Configure environment
cp .env.example .env
nano .env  # Set:
          # - COUCHBASE_PASSWORD
          # - JWT_SECRET
          # - GITHUB_TOKEN
          # - GITHUB_REPOS (comma-separated list or use pipeline_ingestion.py)
          # - EMBEDDING_BACKEND=local (recommended - 10-20x faster)
          # - REPOS_PATH=/path/to/repos (outside project to prevent recursion)

# 2. Pull AI models (for Ollama - optional if using local embedding)
ollama pull nomic-embed-text  # optional - only if EMBEDDING_BACKEND=ollama
ollama pull codellama:13b     # for code generation/chat

# 3. Start services
docker-compose up -d

# 4. Initialize database (first time only)
docker exec -it codesmriti_couchbase /opt/init-couchbase.sh

# 5. Generate API key and trigger ingestion
python3 scripts/generate-api-key.py
curl -X POST http://localhost/api/ingest/trigger \
  -H "Authorization: Bearer YOUR_API_KEY"

用法

MCP工具

CodeSmriti提供以下MCP工具：

`search_code`

在所有索引存储库中搜索代码。

{
  "name": "search_code",
  "arguments": {
    "query": "user authentication with JWT",
    "repo": "myorg/api-server",
    "language": "python",
    "limit": 10
  }
}

`get_code_context`

检索包含元数据的特定代码文件。

{
  "name": "get_code_context",
  "arguments": {
    "repo": "myorg/api-server",
    "file_path": "src/auth/jwt.py",
    "function_name": "verify_token"
  }
}

`find_similar`

查找与给定代码段类似的代码。

{
  "name": "find_similar",
  "arguments": {
    "code_snippet": "async def fetch_user(id: int):\n    return await db.query(...)",
    "language": "python",
    "limit": 5
  }
}

`add_note`

添加带有标签的记忆笔记。

{
  "name": "add_note",
  "arguments": {
    "content": "We decided to use JWT for auth because...",
    "hashtags": ["authentication", "architecture-decision"],
    "project": "api-server"
  }
}

`query_by_hashtag`

通过标签检索内容。

{
  "name": "query_by_hashtag",
  "arguments": {
    "hashtags": ["authentication", "best-practices"],
    "content_type": "all"
  }
}

`list_repos`

列出所有索引存储库。

{
  "name": "list_repos",
  "arguments": {}
}

REST API

CodeSmriti还提供REST API端点：

# Trigger manual re-indexing
POST /api/ingest/trigger
Authorization: Bearer YOUR_API_KEY

# Add a memory note
POST /api/notes
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
  "content": "Note content in markdown",
  "hashtags": ["tag1", "tag2"],
  "project": "project-name"
}

# Get system status
GET /api/status
Authorization: Bearer YOUR_API_KEY

从克劳德桌面连接

看 docs/MCP-USAGE.md 有关将CodeSmriti连接到Claude Desktop或其他MCP客户端的详细说明。

管理

查看日志

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f mcp-server
docker-compose logs -f ingestion-worker
docker-compose logs -f couchbase

重新启动服务

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart mcp-server

停止代码写入

docker-compose down

# To also remove volumes (WARNING: deletes all data)
docker-compose down -v

重新索引存储库

# Trigger re-indexing via API
curl -X POST http://localhost/api/ingest/trigger?repo=owner/repo \
  -H "Authorization: Bearer YOUR_API_KEY"

为团队成员生成API密钥

./scripts/generate-api-key.py

# Follow the prompts to create a new API key
# Share the key securely with team members

发展

项目结构

CodeSmriti/
├── docker-compose.yml           # Main orchestration
├── .env.example                 # Environment template
├── mcp-server/                  # FastMCP server
│   ├── server.py                # Main server
│   ├── config.py                # Configuration
│   ├── tools/                   # MCP tools
│   ├── resources/               # MCP resources
│   └── auth/                    # Authentication
├── ingestion-worker/            # Background ingestion
│   ├── worker.py                # Main worker
│   ├── parsers/                 # Code/doc parsers
│   └── embeddings/              # Embedding generation
├── api-gateway/                 # Nginx configuration
├── scripts/                     # Management scripts
└── docs/                        # Documentation

添加对新语言的支持

编辑 ingestion-worker/config.py:

supported_code_extensions = [".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs"]

在中添加树状图解析器 ingestion-worker/parsers/code_parser.py:

self.parsers = {
    "python": get_parser("python"),
    "javascript": get_parser("javascript"),
    "typescript": get_parser("typescript"),
    "go": get_parser("go"),  # Add new language
}

添加对新文档格式的支持

更新 ingestion-worker/config.py:

supported_doc_extensions = [".md", ".txt", ".json", ".yaml", ".yml", ".pdf"]

在中实现解析器 ingestion-worker/parsers/document_parser.py.

故障排除

沙发无法启动

# Check logs
docker logs codesmriti_couchbase

# Ensure ports are not in use
lsof -i :8091-8097

# Reset Couchbase
docker-compose down
docker volume rm codesmriti_couchbase_data
docker-compose up -d couchbase

MCP服务器无法连接到Ollama

确保Ollama在Mac上本机运行：

# Check if Ollama is running
curl http://localhost:11434/api/version

# If not, start it
ollama serve

摄入工人失败

# Check logs
docker logs codesmriti_ingestion_worker

# Common issues:
# - Invalid GitHub token (check .env)
# - Repository doesn't exist or is private
# - Network issues

矢量搜索不起作用

确保在Couchbase中创建了向量搜索索引：

# Access Couchbase UI
open http://localhost:8091

# Navigate to Search → Full Text Search
# Create index using the definition from init-couchbase.sh

演出

V4摄入 （Mac M3 Ultra，配备qwen2.5-coder-7b的LM Studio）：

101个存储库：总共32小时（约20分钟/回购平均）
48795份文件：13K文件，31K符号，4K模块
LLM代币：每个文件约1850（估计输入+输出）
嵌入生成：~1280文档/分钟（苹果硅MPS）

搜索性能:

矢量搜索延迟：\<100ms
并发请求：50多个同时进行的MCP呼叫
多级查询：符号→ file → 模块→ repo

安全

基于JWT的身份验证，具有可配置的过期时间
API密钥可以定域（读/写/管理）
Nginx支持速率限制
HTTPS/TLS就绪（在api gateway/中配置证书）
安全存储在环境变量中的GitHub令牌

路线图

\[\]完成Couchbase存储集成
\[\]添加WebSocket支持以进行实时更新
\[\]实现PDF文档解析
\[\]添加对更多编程语言（Go、Rust、Java）的支持
\[\]创建用于浏览和管理内容的web UI
\[\]添加GitHub webhook集成以自动重新索引
\[\]实施用户管理和团队工作区
\[\]添加度量和可观察性（普罗米修斯/Grafana）

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

CodeSmriti是开源的，可以免费使用、修改和分发。

支持

如有疑问或问题：

检查日志： docker-compose logs -f
审查文档 docs/
联系团队

______________________________________________________________________

内置于🧠 因为我们从未忘记上次是如何解决那个问题的。

Code Smriti

快速接入

详细介绍