内容
PG-Git（语义记忆引擎）
<p align="center">
<img src="assets/banner.png" alt="PG-Git Banner" width="100%">
</p>
一个持久的、基于PostgreSQL的代码仓库管理系统和人工智能IDE的语义记忆引擎。 PG-Git 将整个有向无环图（DAG）原生存储在 PostgreSQL 中，并附带自动生成的、时间衰减的语义向量嵌入。
[](https://badge.fury.io/js/pg-git-mcp)
[](https://opensource.org/licenses/ISC)
## 🧠 为什么选择 PG-Git？
在标准的人工智能编码代理生态系统中，搜索代码库依赖于严格的 grep 搜索贵的 AST 解析。 PG-Git 通过将 Git 直接数据库桥接，彻底改变了这一点：
1. **语义代码搜索**：根据代码的作用查找代码，而不仅仅是其语法。
2. **指数时间衰减**：PG-Git 数学上衰减较旧的向量。您的代理将优先考虑昨天编写的代码，而不是 6 个月前编写的高度相似的死代码。
3. **本地优先纯度**：无云 API。它使用 Ollama 和 `bge-large` 在设备上进行 100% 私有、本地的向量化，维度为 1024。
4. **ACID 合规**：原生事务确保多节点可访问性和并发 AI 群集代理的安全性。
## ⚠️ 不是 Git 的替代品
必须了解-Git **不替换 Git** 或 GitHub/GitLab 等服务。它不处理分支合并、变基或拉取请求。
相反，PG-Git 是一个 **代理增强层**。您继续使用标准的 Git 进行面向人类的源代码控制和团队协作。 PG-Git 位于您的工作流中，自动摄取您的标准 Git 历史记录，为您的 AI 代理提供一个数学优化的、可语义搜索的代码库克隆。
## 🔒 可靠性审计和指针解析
为了保证生产级稳定性和orepo 的完整连续性，PG-Git 经过了彻底的架构审计和可靠性大修：
1. **确定性指针解析**：在标准 `'pointer'` 存储模式（用于保持数据库轻量级）中，文件内容存储为 PostgreSQL 中的 `NULL`。我们在 `-engine.js` 中引入了一个动态解析器，映射相对 blob 路径到本地文件系统 monorepo 根目录。这会自动按需从磁盘流式传输原始文件内容，解决了 Express `/api/blobs/:id` 路由和 `pg_git_read_blob` MCP 工具上的 `null` 值崩溃问题。
2. **安全的语义搜索预览**：标准语义搜索工具调用如果尝试字符串化可为空的数据库列，则会抛出 TypeError。 PG-Git 现在安全地提取预编译的` 列（使用wen2.5-coder:14b` 内生成），作为上下文预览。
3. **防止饥饿的队列管理**lib/llm-` 中的 fleet 优先级队列（`PriorityQueue.process`）使用严格的 `try ... 块保护。这保证了在所有任务结果下，都会干净地释放并发槽（`this.active--`），防止内存和槽泄漏，否则这些泄漏将阻止多代理群集操作。
4. **保真度嵌入补全**：升级的 `backfill_embeddings.js` 以在处理指针模式 blob 时自动解析本地磁盘路径。这使嵌入补全过程能够从原始代码出真度、后的质心嵌入，而不是依赖于有损、缩短的摘要片段。
## 🤝 代理大脑（与 Krusch Context MCP 的协同作用）
PG-Git 设计为 **代码库引擎**，位于 **[Krusch Context MCP](https:///kruschdev/krusch-context-mcp)** 之下 - 一个统一的下文服务器，它将语义代码搜索、情景全息 nuggets 折叠成单个 MCP 进程。
虽然 PG-Git自己的 MCP 服务器（通过 `server/mcp.js`）独立运行，但其全部在被 Krusch 使用时才能实现| 层级 | 来源 | 目的 |
| --- | --- | --- |
| **代码库内存（”和“怎么做”）** | PG-Git `blobs` 表 | 整个代码库的语义嵌入源文件 |
| **情景记忆（“为什么”）** | Kruschide_agent_memory` | 架构决策、遇到的错误、项目目标 |
| **全息 nuggets（“如何表现”）** | Krusch Context `ide_agent_nuggets` | 轻量级导航事实、用户偏好、项目约定 |
**无限连续性**：通过运行 Krusch Context MCP（它直接导入 PG-Git 的数据库连接池和嵌入逻辑），您的代理可以交叉引用 **意图**（）与 **实现**（代码库 blobs）。它记得 **为什么** 您选择了特定的架构，并立即看到 **如何** 实现它，创建一个深入上下文化和自治的编码工作流，该工作流在无限会话中持续存在。
> 🔗 **查看完整统一服务器文档：Krusch Context](https://github.com/kruschdev/krusch-context-mcp)
## ⚡ 快速入门
必须** 运行带有 `bge-large` 嵌入模型的 [Ollama](https://ollama.com/)：
```bash
ollama pull bge-large
```
**1. 克隆和迁移数据库**
您需要一个启用了 `pgvector` 的正在运行的 PostgreSQL 实例。
```bash
git clone https://github.com/kruschdev/pg-git.git
cd pg-git
npm install
cp .env.example .env
# 使用您的 PostgreSQL 凭证编辑 .env
node db/migrate.js**2. 导入 GitHub 历史记录**
WARNING]
> **谨慎选择嵌入模型。** 您运行第一个导入或之前通过 Web UI 设置选项卡或 `.env首选模型。 如果稍后更改模型，向量维度将发生冲突，您将被迫手动清除数据库并从头重新嵌入所有存储库。
您可以即时导入任何本地 `.git` 存储库。 PG-Git 将原生解析 Git 历史记录，为所有语义嵌入，并安全地将它们重复数据删除到 PostgreSQL：
```bash
npm run import
```
a. 通过 Krusch Context MCP 使用（推荐）**
使用 PG-Git 的推荐方式是通过 [Krusch Context MCP](https://github.com/kruschdev/krusch-context-mcp) 统一服务器，它 PG-Git 的数据库连接池和嵌入逻辑，以及情景记忆和 nuggets。有关设置说明，请参阅 [Krusch Context MCP 快速入门](https://github.com/kruschdev/krusch-context-mcp-start)。
**3b. 使用独立 MCP 服务器您喜欢以隔离的 MCP 服务器运行 PG-Git，可以直接通过 NPM 执行它。将其添加到您的代理 配置（例如 `m.json`）：
```json
{
"mcpServers": {
"pg-git-mcp": {
"command": "",
"args": ["-y", "pg-git-mcp"],
"env": {
"PG_CONNECTION_STRING": "postgres://user:pass@localhost:/kruschdb",
"OLLAMA_URL": "http://localhost:11434",
"EMBED_MODEL": "bge-large"
}
}
}
}
```
**4. 启动 Web UI（可选）**
PG-Git 包含一个时尚的双窗 界面，用于浏览语义存储库。
```npm run dev
## 🔧 MCP（独立模式）
以独立 MCP 服务器运行 PG-Git 时，它会公开以下工具：
| 工具 | 描述 |
| --- | --- |
| `pg_git_list_repos` | 列出数据库中存储的所有 PG-Git 存储库 |
| `pg_git_read_tree` | 读取特定存储库的目录结构 节点| `pg_git_read_blob` | 读取特定 blob 的文件内容 |
| `pg_git_semantic_search` | 对索引文件进行语义搜索，并带有时间衰减评分 |
> [!NOTE]
> 通过 **Krusch Context MCP** 使用时，这些功能会在统一工具名称下公开（`krusch_context_search、`krusch_context_read_tree`、`krusch_context_read_blob`、`krusch_context_list_repos`），以及 14 种额外的记忆和 nugget 工具## 🚀 现实世界使用示例
###模式
与 IDE 代理正常交互。它将使用独立的 MCP 数据库接口：
1：查找**
> **您 “我们在内存 MCP 中如何处理时间衰> **代理：** *[调用 `pg_git_search`]* “我在 `server/git-engine.js`逻辑。它在 `searchBlobs()` 中exp(-0 * age_in_days。”
**2：读取存储**
> **您 “pg-git 项目结构是什么？”
> **代理：** *[调用_git_read_tree “这是根目录结构...”
**示例 3：按项目过滤**
> **您：在 pocket-lawyer搜索身份验证逻辑。”
> **代理：调用 `pg_git_semantic_search` 并带有: 'pocket-lawyer'`]* “ 模块中找到 3项...”
衰减如何工作调用 `pg_git_sem` 时，it 返回最高余度匹配。但是，它会 的 `last_seen_at` 时间戳应用 **衰减**：
= cosine_similarity × exp(-0.01 × age_in_days)
```
如果您有两个非常相似的代码片段，较新的代码片段将具有明显更高的分数，从而防止您的代理根据过时的实现产生幻觉。
---
## 🤖 自主代理工作流
您可以将 PG-Git 集成到您的代理工作流中，以确保您的语义记忆始终是最新的。
### 快照（单个项目）
每当您离开任务时，告诉运行快照脚本。代理将自主：
1. 将文件夹哈希到 Git Blobs 和 Trees。
2. Ping Ollama 嵌入或修改过3. 直接将到 PostgreSQL。
npm run snapshot### 同步所有全fleet范围）
重新索引fleet中所有活跃的项目代码库：
```bash
npm run sync-all
```
### 外部文档同步
PG 可以摄取外部例如 `llms.txt` 清单）以实现无幻觉的框架知识：
```bash scripts/sync_external
```
---
📂 项目结构
-git/
├── server/
│ ├── index.js # Express API + 服务器
│ ├── mcp.js # 独立 MCP 服务器（StdioServerTransport）
│ └── git-engine.js # Git DAG 操作 + 语义搜索与时间
├── db/
├── schema.sql # PostgreSQL 模式（commits、branches、blobs + pgvector）
│ ├── pool # 共享 pg.Pool 连接
│ ├── migrate.js # 器
│ ├── create-db.js 创建助手
│ list-dbs.js 列出可用数据库
├── lib/
│ └── embedding.js # 带有fleet负载均衡的共享ama嵌入客户端 scripts/
│ _to_pg.js 单个项目快照到
│ ├── sync_all_projects.js # 全fleet范围的项目│ ├── sync.js # 外部取（llms.txt）
│ ├── import_github.js # .git 历史记录 ├── import_hf_dataset.js # 导入 HuggingFace 数据集 ├── backfill_embeddings.js # 补全的嵌入 ├── migrate_to_1024.js # 维度迁移助手
│ ├── migrate_to_pointer.js # 存储模式迁移
│ └── scaffold_nesting_dolls.js # 嵌套娃娃分块脚手架
├── client/ # Vite + React Web UI
├── config/
│ └── external_docs.json 外部文档清单
├── config.js # 统一配置（env + config.json 合并）
├── assets/ #和社交预览图像
├── Dockerfile # 多阶段生产构建
├── docker-compose.yml # 容器编排
├── AGENTS.md # AI IDE上下文规则
└── spec.md # 原规范
```
---
🛠️ 配置和
PG-Git层配置系统变量覆盖 `config.json`，后者覆盖。
| 变量 | 默认值 |
| --- | --- `PORT` |端口 | `4890` |
| `` | PostgreSQL 主机地址 | `localhost| `DB_PORT` | PostgreSQL 端口5434` |
DB_NAME` | `postgres` `DB_USER 数据库用户 | ` |
| `DB | 数据库密码 |)* |
| `_URL` | 本ama 实例的 | `http://11434` |
EMBED_MODEL`| Ollama 文本嵌入 `bge-large` |
### 数据库模式-Git 的 PostgreSQL 模式直接将映射到 SQL 表
- **`repositories 项目注册表
- **`commits`**树和父 SHA-1 确定的提交对象
- **` — 命名引用头部
-`** / **`tree — 目录结构，将到 blob/tree 对象- **`blobs`** — 文件内容，embedding vector(1024)` 和 `last` 时间跟踪义搜索使用vector_cosine_ops `pgvectorNSW 索亚毫秒级最近邻查找。
---
## 🗺项目
| 项目 | 角色 |
| --- | --- |
| **[Krusch Context MCP://github.com/kruschdev/krusch-context-mcp)** | 统一 IDE 上下文服务器 — 将 PG-Git + 情景记忆 + nuggets 包装成单个 MCP 进程 |
| [NPM 上的 PG-G://www.npmjs.com/package/pg-git-m
