agentRamen

agentRamen

采用 Apache-2.0 许可证。请参阅安全策略和社区行为准则。

agentRamen 为源代码结构和 Git 历史建立索引，然后检索与任务相关的文件和摘录。默认采用本地优先模式：每位开发者都保留自己的私有 SQLite 索引。团队也可以选择将经过脱敏、固定到特定提交的快照发布到集中托管并受 OIDC 保护的只读 MCP 服务。

快速开始

安装 agentRamen，然后在要探索的仓库中运行：

python -m pip install agentramen
cd /path/to/your/repository
agentramen init
agentramen context "Add authentication" --budget 2000
agentramen impact src/auth.py

agentramen init 会创建配置、为仓库建立索引，并提供可选的 GitHub Actions 调用工作流。索引存储在本地的 .agentramen/graph.db 中。

通过 examples/demo.sh 在 30 秒内试用。请参阅路线图和贡献指南。

此外还提供一个精简的 VS Code 扩展。

功能

• 查找任务上下文： 根据路径、符号、导入、Git 历史和可选的本地语义相似度为文件排序。
• 解释变更影响： 检查依赖项、被依赖项、共同变更、热点和文件历史。
• 梳理仓库结构： 探索架构、导出图，并查询缓存的提交快照。
• 连接编码 Agent： 使用本地 MCP stdio、浏览器界面，或可选的经过身份验证的集中式 MCP 服务。
• 保护本地索引隐私： 在本地模式下，数据库和可选的嵌入向量保留在各自的检出目录中；在集中模式下，仅将明确指定且经过脱敏的快照传输到由你运营的基础设施。

工作原理

flowchart LR
  repo[Working tree and Git history] --> indexer[Indexer and language analyzers]
  indexer --> db[(Local SQLite graph)]
  optional[Optional local embeddings] --> db
  task[Task or query] --> clients[CLI, MCP, or local HTTP]
  clients --> retrieve[Retrieval and graph queries]
  retrieve <--> db
  retrieve --> excerpts[Ranked files and source excerpts]

默认安装使用 Python 标准库，并对其他语言采用保守分析。可选扩展可提供 Tree-sitter 解析、本地语义检索和模型感知的令牌计数。

对比

项目	Stars	方案	与 agentRamen 的对比
Serenagithub	~30.1k	基于 LSP 的语义检索与编辑工具包，MCP	功能范围广得多，采用度也高得多的 Agent 工具包
Aider's RepoMapgithub	~49.4k	Tree-sitter + PageRank，根据令牌预算生成仓库映射	图排序、令牌预算仓库上下文的成熟范例（相邻领域：编码应用中的一项功能）
Repomixgithub	~28.7k	将整个仓库打包成一个适用于 AI 的文件	相邻工作流：整仓打包与选择性上下文
code-index-mcpgithub	~1k	使用 Tree-sitter AST 支持 10 种语言，持久化索引，MCP stdio	结构上最相近的独立索引服务；未提及语义搜索或 CI 集成
agentRamen	1	SQLite 图谱、Git 历史排序、MCP+CLI+HTTP+VS Code	刚推出、可用的 alpha 版本

可选附加功能

python -m pip install 'agentramen[treesitter]'
python -m pip install 'agentramen[semantic]'
python -m pip install 'agentramen[tokenizer]'
python -m pip install 'agentramen[central]'

默认安装没有运行时依赖。Tree-sitter、语义嵌入、分词器和远程 MCP 服务均为可选项。语义模型设置可能会在首次使用时下载权重；推理在本地运行。

如果 .agentramen.yml 和 GitHub Actions 调用工作流不存在，agentramen init 会创建它们，然后创建或更新 .agentramen/graph.db。agentramen update 和 agentramen index 会增量刷新已更改的文件。数据库会被 Git 忽略。

在本地模式下，源代码摘录和可选嵌入会保留在 .agentramen/graph.db 中。中央快照模式会将通过凭据启发式检查的已索引源代码传输到你的私有中央服务；启用前，请确认符合所在组织的数据处理要求。

发布版本

为 palrajjp/agentRamen 配置 PyPI 可信发布者，使用 .github/workflows/publish.yml 工作流和 pypi 环境。要发布 一个版本，请更新 pyproject.toml 和 agentramen/__init__.py 中的版本号， 创建匹配的、以 v 开头的 Git 标签，并为该标签发布 GitHub 版本。 该工作流会构建发行包，并通过 OIDC 将其发布到 PyPI。

配置

agentRamen 从 .agentramen.yml 读取以下字段：

version: 1
indexing:
  incremental: true
git:
  history: true
  co_changes: true
history:
  commits: 100
semantic:
  enabled: false
  model: BAAI/bge-small-en-v1.5
context:
  default_budget: 2000
  tokenizer_model: ""
ignore:
  - .env
  - "*.pem"
  - private/

indexing.incremental: false 会在每次索引时重新解析所有符合条件的文件。git.history: false 会移除存储的提交、重命名和共同变更历史；之后启用时，会重建配置的近期历史。history.commits 控制保留的提交数（1–100,000），git.co_changes 用于启用或禁用共同变更关联。未传入预算时，CLI、MCP 和 HTTP API 会使用 context.default_budget。配置采用无依赖的 YAML 子集；不受支持或格式错误的值会触发针对相应设置的错误。.agentramenignore 中的模式会添加到内置和 YAML 忽略规则中，而非替换它们。

semantic.enabled: true 表示选择启用本地嵌入生成和语义上下文排序；请先安装 agentramen[semantic]。semantic.model 用于选择 FastEmbed 模型。安装 agentramen[treesitter] 表示选择启用基于 Tree-sitter 的解析，适用于受支持的非 Python 语言；如果未安装此依赖，或语法不可用，agentRamen 会回退到正则表达式分析。

context.tokenizer_model 可选用于选择 tiktoken 支持的模型，以便按分词器计算上下文预算；请安装 agentramen[tokenizer] 后使用。分词器词汇表可能会在首次使用时下载并缓存，之后计数将在本地运行。留空则使用无依赖的近似字符计数回退方案。上下文响应会标明 token_count_method（tiktoken 或 approximate），并在已配置时提供分词器模型。报告的总预算会一并计算所选文件、团队记忆以及路径／摘要／提交证据；每个文件的计数会以 estimated_tokens 提供。

命令

agentramen init
agentramen index [--json]
agentramen update [--json]
agentramen status [--json]
agentramen context "Add OAuth login" [--budget 2000] [--json]
agentramen impact src/auth/AuthService.ts [--json]
agentramen explain src/auth/AuthService.ts [--json]
agentramen history src/auth/AuthService.ts [--json]
agentramen search "auth login" [--limit 20] [--json]
agentramen architecture [--at <commit>] [--json]
agentramen hotspots [--limit 20] [--json]
agentramen changes [--limit 20] [--json]
agentramen diff <commit1> <commit2> [--json]
agentramen pr [--base origin/main] [--json]
agentramen export [--at <commit>] [--json]
agentramen benchmark --files 10 1000
agentramen serve [--host 127.0.0.1] [--port 8765]
agentramen mcp

上下文响应示例：

{
  "task": "Add authentication",
  "files": [
    {
      "path": "src/auth_service.py",
      "language": "python",
      "symbols": ["AuthService"],
      "imports": [],
      "recent_change": "add authentication",
      "estimated_tokens": 18
    }
  ],
  "token_budget": 2000,
  "files_avoided": 12,
  "confidence": "medium"
}

只有当文件仍与其索引哈希匹配且不包含检测到的凭据模式时，上下文才会包含源代码摘录。如果有可用的已配置模型分词器，则使用它计算 Token 数；否则会使用基于字符的近似估算，这不是分词器测量结果，也不代表性能声明。

GitHub Actions

由 agentramen init 创建的工作流会调用此仓库中的可复用工作流：

name: agentRamen
on:
  push:
    branches: ["**"]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "17 4 * * 1"
jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main

可复用工作流会获取 Git 历史、恢复缓存、测试已安装的软件包、索引已检出的修订版本、汇总拉取请求，并发布本地 SQLite 工件。在此可复用工作流之外运行 CLI 时，请使用完整深度检出以保留历史。

在 gha-cd 或其他工作流中使用

在部署或 Agent 作业之前调用此可复用工作流。提供 task 还会创建一个有界的 JSON 上下文工件；该工作流不会向 AI 服务提供商发送仓库内容。

jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
    with:
      task: "Trace the deployment workflow and identify rollback dependencies"
      token_budget: 1200

工件名称为 agentramen-context-${{ github.sha }}。下游作业可以获取它，并将 .agentramen-context/agentramen-context.json 传递给其 Agent 步骤：

- uses: actions/download-artifact@v4
  with:
    name: agentramen-context-${{ github.sha }}
    path: .agentramen-context

如果省略，上下文预算默认为 2000。请像对待源代码一样对待该工件：它可能包含摘录，并遵循仓库的 GitHub Actions 访问和保留策略。

Agent 集成

agentRamen 的 MCP 服务通过 stdio 在本地运行。在每台开发者机器上安装一次 agentRamen，然后在仓库根目录添加可移植的 .mcp.json，这样 VS Code Copilot 和 Claude Code 就能使用相同的配置：

python -m pip install git+https://github.com/palrajjp/agentRamen.git

{
  "mcpServers": {
    "agentramen": {
      "type": "stdio",
      "command": "agentramen",
      "args": ["mcp"]
    }
  }
}

对于 Claude Code，项目级命令会创建或更新 .mcp.json：

claude mcp add --transport stdio --scope project agentramen -- agentramen mcp

对于 GitHub Copilot CLI，将相同的 mcpServers 对象保存到 $COPILOT_HOME/mcp-config.json；若未设置 COPILOT_HOME，则保存到 ~/.copilot/mcp-config.json。有关客户端特定的设置和信任提示，请参阅 VS Code MCP 配置指南 和 Claude Code MCP 指南。

在 VS Code 中，信任工作区并从 MCP Servers 视图启动 agentramen MCP 服务。每位开发者都保留独立的 .agentramen/graph.db；提交 .agentramen.yml 和 .mcp.json 以共享设置，但不要将正在使用的 SQLite 数据库放在网络共享目录中。

让 Agent 上下文保持聚焦

在项目的 AGENTS.md、CLAUDE.md 或 Copilot 指令中添加类似这样的指令：

分析仓库时，先针对当前任务调用 repo_context，再广泛读取文件。先将预算设为 1200 个 token，以返回的路径作为调查范围，然后调用 repo_explain 或 repo_impact 进行有针对性的后续调查。仅当索引上下文不足时才扩大搜索范围。如果索引似乎已过时，请运行 agentramen update。

预算限制的是检索到的上下文，而非模型的整个对话。默认使用基于字符数的近似估算；如果需要针对特定模型进行计数，请安装 agentramen[tokenizer] 并设置 context.tokenizer_model。更改后运行 agentramen update，以增量刷新开发者的本地索引。

ChatGPT 和 GPT Store

自定义 GPT 无法启动开发者本地的 stdio 进程。GPT Action 或托管的 ChatGPT 应用需要可访问且带身份验证的 HTTPS 服务。agentramen serve 绑定到 localhost 且不提供身份验证，因此不要将其直接暴露到互联网；安全的远程集成需要经过身份验证的网关或单独托管的 MCP 服务。能否创建和发布 GPT 取决于当前的 ChatGPT 方案和工作区策略；请参阅 OpenAI 的 GPT 创建指南。

MCP

在仓库中运行 agentramen mcp，并将兼容 MCP 的 Agent 配置为在仓库工作目录中启动该命令。工具包括 repo_context、repo_status、repo_history、repo_search、repo_explain、repo_impact、repo_dependencies、repo_tests、repo_changes、repo_architecture、repo_hotspots、repo_graph、repo_stage_memory、repo_review_queue、repo_approve_memory、repo_reject_memory、repo_publish_memory、repo_team_memory_search 和 repo_memory_audit。stdio 服务不需要 API 密钥，也不会访问网络服务。

本地 HTTP API

默认情况下，agentramen serve 仅监听 127.0.0.1。浏览器界面可通过 / 和 /ui 访问。API 提供 GET /health、GET /api/v1/repository、/architecture、/graph、/files/{path}、/impact?path=...、/history?path=...、/hotspots，以及 POST /api/v1/context 或 POST /api/v1/search。在 /api/v1/graph 或 /api/v1/architecture 后追加 ?at=<commit>，即可查询可按提交定位的缓存图快照。POST 请求接受 JSON 对象，例如 {"task":"Add OAuth","token_budget":2000}。此服务不提供身份验证；若要绑定到公共接口，必须先在前面设置经过身份验证的访问控制层。

基准测试

运行 agentramen benchmark --files 10 1000，测量合成数据的初始索引、单文件增量更新和上下文检索。添加 --repository /path/to/repo，还可测量真实代码仓库已跟踪工作树文件的临时副本。使用 --semantic-mode both 可比较关闭和启用语义检索时的表现；启用语义检索需要安装 agentramen[semantic]，并会在需要时下载其配置的模型。如果无法设置模型，比较结果会将该模式报告为错误，但仍会返回成功模式的测量结果。输出包含词法候选项数量、数据库大小，以及检索和索引耗时。

添加 --quality，可在确定性且带标签的合成测试样例上报告任务到文件以及受影响测试的精确率和召回率；test_evidence 展示用于确认每个建议测试的导入链：

agentramen benchmark --quality --json

当前测试样例的文件和测试平均精确率与召回率均为 1.0。这是对测试样例正确性的检查，并不代表真实代码仓库中的准确率。做出采用决策时，请根据自己的代码仓库整理标签并测量这些任务；所有耗时和分数都取决于代码仓库、任务标签和环境。

隐私与排除项

索引保存在本地计算机的 .agentramen/graph.db 中，或保存在配置的 CI 工件中。关闭语义检索时，数据库会存储源文件元数据和哈希值；启用后，还会存储本地生成的嵌入。agentRamen 会跳过常见的生成目录、环境文件、私钥文件、超大文件、二进制文件，以及包含可识别私钥或凭据赋值模式的文件。可在 .agentramenignore 中添加更多路径模式（每行一个模式）。发布生成的工件前，请检查忽略规则。

检索与记忆

上下文检索使用增量 SQLite 倒排索引获取词法候选项，然后通过互惠排名融合结合词法、可选的语义以及图谱／历史排名，再应用令牌预算。经审核的记忆可暂存、批准或拒绝；批准一条新事实时，会取代具有相同主体且与之冲突的有效事实。

与团队共享已审核的记忆

AgentRamen 会将实时 SQLite 数据库保留在每个检出目录中，不对外共享。要共享已审核的事实，请先将其暂存并批准，然后发布到 .agentramen-shared/memories/<id>.json。在拉取请求中提交该文件，让团队成员审核更改、查看历史记录，并通过 Git 获取更新。每条记忆单独存放在一个文件中，可避免互不相关的新增内容发生冲突。

MCP 工具：repo_context 会返回其所选文件的源路径、摘要和提交证据。随后调用 repo_stage_memory，会将最近一次上下文调用的证据附加到本地待处理提案中；审核时会显示这些证据，以及源文件内容是否仍为最新。批准时会将 Git user.name 记录为审核者（若未设置，则使用本地账户名）；发布时会保留审核者、源提交、摘要和有效期。若证据已变更，批准和发布都会被拒绝。过时的已批准记忆会显示在 repo_review_queue 顶部，并提供 restage_with_fresh_context 操作；无法将其重新批准为当前有效记忆。repo_team_memory_search 不会返回证据已过时或缺失的共享记忆。repo_memory_audit 会报告唯一的过时记忆数量、路径不匹配、源提交，以及未经验证的本地或共享记录，但不会修改共享 Git 文件。发布具有相同主题的较新已批准事实时，会在被取代事实的现有文件中将其标记为已取代。系统会阻止发布类似凭证的内容；提交前仍应检查记忆内容，确保其中不含机密或个人数据。未经明确的人为指示，Agent 不应批准或发布记忆。

CLI 搜索和发布：

agentramen memory search "authentication provider"
agentramen memory publish <approved-memory-id>
agentramen memory audit --json

共享记忆采用选择加入方式，并由版本控制；被拒绝或仅暂存的笔记会保留在本地。在捕获源证据之前创建的现有记忆会被报告为未经验证，在补充证据并重新暂存之前，不会纳入任务上下文。源文件发生变更或缺失时，即使尚未运行 agentramen update，关联记忆也会变为过时；请刷新上下文并提出新的记忆，而不要悄然将旧事实视为当前有效。不要通过网络共享目录同步 SQLite。对于 100 人的团队，共享记忆变更应使用受保护的分支，并遵循常规拉取请求审核流程。

用于共享图谱的集中式 MCP

本地 stdio 仍是默认方式。若要为远程 Agent 发布不可变的图谱快照，请启用可选的中心化依赖项和可复用工作流输入：

jobs:
  index:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
    with:
      central_snapshot: true
      repository_id: acme/payments-monorepo

工作流会先通过 agentramen snapshot verify 验证归档，然后上传 agentramen-snapshot-${{ github.sha }}。归档包含固定版本的图谱、通过凭据过滤并经哈希验证的索引源代码，以及已提交的团队记忆。开发者私有的 SQLite 记忆和本地排除规则会被剔除。工件会在 14 天后过期，因此请在过期前将已接受的快照复制到私有的公司持久化存储中。如果 agentramen init 生成了 .github/workflows/agentramen.yml，请在导出前提交该文件；导出快照要求源代码检出状态干净。

为每个仓库快照部署一个只读 MCP 服务。该服务会根据 JWKS、颁发者、受众、有效期、范围以及可选的组声明验证公司 OIDC JWT；DNS 重绑定防护要求显式设置 Host 允许列表。请在可信的入口处终止 TLS，并将归档和挂载的快照保留在公司控制的基础设施中。

python -m pip install 'agentramen[central]'
export AGENTRAMEN_OIDC_ISSUER="https://login.example.com/tenant/v2.0"
export AGENTRAMEN_OIDC_JWKS_URL="https://login.example.com/tenant/discovery/v2.0/keys"
export AGENTRAMEN_OIDC_AUDIENCE="agentramen-api"
export AGENTRAMEN_OIDC_RESOURCE_URL="https://agentramen.example.com/mcp"
export AGENTRAMEN_OIDC_REQUIRED_SCOPE="agentramen:read"
export AGENTRAMEN_OIDC_ALLOWED_GROUP="engineering"
export AGENTRAMEN_MCP_ALLOWED_HOSTS="agentramen.example.com"
agentramen mcp-http \
  --snapshot-archive /srv/agentramen/current-snapshot.zip \
  --repository-id acme/payments-monorepo \
  --host 0.0.0.0 --port 8000

将 MCP 客户端配置为使用 HTTPS /mcp 端点，并完成公司的 OAuth/OIDC 流程。例如，Claude Code 可以通过 claude mcp add --transport http agentramen-central https://agentramen.example.com/mcp 添加该服务；VS Code 支持远程 HTTP MCP 服务。如果你的 IdP 使用不同的组声明，请设置 AGENTRAMEN_OIDC_GROUP_CLAIM（默认值为 groups）。

远程工具为只读工具：状态、上下文、搜索、架构、图谱和已批准的团队记忆搜索。每个响应都会包含 repository_id 和 snapshot_commit，方便 Agent 识别过时的建议。

为确保部署的新鲜度并支持回滚，请将每个已接受的归档设为不可变，并以提交 SHA 作为键。验证归档，使用该归档启动候选服务，然后通过经过授权的客户端调用 repo_status，确认提交符合预期。通过原子性地将入口/服务指针切换到候选服务来完成上线；保留之前的服务/归档，并通过将指针切回实现回滚。请勿覆盖正在运行的服务所使用的归档。agentramen mcp-http 仅运行一个进程；请使用平台的进程管理器/负载均衡器，并为副本提供共享的只读快照挂载。特定云服务的存储上传和指针切换属于部署流水线的职责，不包含在此软件包中。

快照包含经过清理但真实的源代码。凭据启发式检测不能替代仓库 ACL 或数据泄露审查；请使用私有、由公司控制的存储，并设置与源仓库相匹配的保留和访问控制策略。

已知限制

• 导入解析支持常见的文件和模块布局，但不支持所有工作区别名或特定语言的构建系统。
• 架构和拉取请求摘要使用索引的依赖关系边，不会应用语义边界规则。
• 语义检索会计算精确相似度，不使用近似最近邻索引。
• 除非使用可选的 tokenizer extra 配置 context.tokenizer_model，否则 Token 数量是基于字符的近似估算。
• 默认保留 100 个提交，可配置范围为 1 至 100,000。

开发

python -m unittest discover -s tests -v
python -m agentramen.cli status --json

如果 agentRamen 对你的工作流有帮助，在 GitHub 上点星有助于其他开发者发现它。请参阅 CONTRIBUTING.md、SECURITY.md 和 CODE_OF_CONDUCT.md。添加语言分析器的贡献应将特定于解析器的行为与索引和上下文接口分开。