Tugra

tugra

属于 VERAX，由 VERAX Teknoloji 开发。从 VERAX 主体项目开始：verax-ai/verax。姊妹项目：Conarium · Cedulon。

收录于：npm · Glama · MCP Registry · MCP Market · LobeHub

npx tugra init

这会创建一个知识库，写入一条示例事实，并打印配置块。将该配置块粘贴到 MCP 客户端中。在 TTY 中，npx tugra 会打印帮助信息并退出。通过管道调用时（Claude Desktop、Cursor、Claude Code），它就是 MCP 服务。

面向 AI Agent、注重来源溯源的记忆。每条声明都带有来源、时效和边界。没有云端。

它是什么

无法说明来源的事实就不是事实。Tugra 将每条声明存储为一个文件，其 frontmatter 包含来源、上次验证日期、保质期，以及在主题不允许讨论时用于禁止编造的边界。搜索结果按 token 得分排序，其次按新鲜度，再按置信度排序。默认结果集不包含已退役和已过期的事实。

工具

工具	功能
fact_search	搜索知识库。除非设置 archive: true，否则不包含已退役／已过期的事实。
fact_read	按 uid 读取一条事实。在模型查看正文前，正文会经过转义处理。
fact_propose	写入草稿。检测到秘密信息模式时，会在写入前拒绝操作。type: "boundary" 始终会被隔离。
event_report	追加一条本地遥测记录。不联网。

存储的字段名称保留知识库的原生格式（kaynak、guven、raf_omru、sinir）。上方的工具名称和参数名称是公开接口约定。

安装 — 环境路径（可选）

运行 tugra init 即可开始。只有在其他位置已有知识库时，才需要覆盖这两个路径。若未设置，服务会在已安装的包旁查找——对于未运行 init 的纯 npx 调用，这不是正确位置。

• TUGRA_VAULT — 知识库（Markdown 格式事实）
• TUGRA_EVENTS — 遥测目录

授权：如果未配置授权存储，则启用单用户模式——无需配置档案即可搜索和提交提案。如果已配置授权存储（yetki/ 目录或 TUGRA_AUTH），则每个 Agent 都需要一个 JSON 档案，否则搜索会返回未授权。

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Claude Code

项目根目录中的 .mcp.json，或运行 claude mcp add：

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Cursor

.cursor/mcp.json 或 Cursor Settings → MCP：

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Windsurf

mcp_config.json：

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.tugra]
command = "npx"
args = ["-y", "tugra"]

[mcp_servers.tugra.env]
TUGRA_VAULT = "/absolute/path/to/vault"
TUGRA_EVENTS = "/absolute/path/to/events"

Windows：使用完整路径（C:\\Users\\…\\vault）。Node 20 或更高版本。

更多客户端说明：docs/install.md。

共享知识库授权（可选）

单用户设置不需要此项。只有在多个 Agent 共享一个知识库，且各自需要独立档案时，才添加 TUGRA_AUTH（例如将 mcp-readonly@tugra 等 JSON 文件放入该目录）。此时，缺少档案会返回未授权。空的 TUGRA_AUTH 会被视为未设置——单用户模式仍会启用。

宿主库接口（非 MCP 线协议）

MCP 工具（fact_search、fact_read、fact_propose、event_report）会在每次调用时执行授权检查。发布的包还提供 dist-paket/akis.js 和 dist-paket/yetki.js，供宿主应用（cron、镜像、驾驶舱）绕过 JSON-RPC 写入遥测数据。

这些模块有意公开。akisBildir({ atlaYetki: true })、eylem: "yetki_talebi" 和 dosyaYoksaIzin（默认值为 true）会跳过或放宽检查。harcamaEkle 会修改配置文件。导入这些模块的宿主负责授权。MCP 线协议无法设置这些标志——工具架构不接受它们。

规模保险库与目标保险库

A0–A5 级别是保险库中的事实（yonetisim.yetki.a0 … a5）。stdio 服务会从 TUGRA_VAULT 读取这些内容；如果未设置该变量，则从驾驶舱的 kasa/ 读取。

tugraArac / createTugraMcp 接受可选的 kasaKok（写入/搜索的目标）。规模不会跟随该目标。默认使用 varsayilanKasa()——与 stdio 服务使用的同一中央保险库。若宿主将 kasaKok 指向仅包含数据的目录树，仍会使用驾驶舱 / TUGRA_VAULT 中的规模。若要从其他目录树读取规模，请显式传入 skalaKasa。

四个工具共用同一个解析器。这就是约定：目标与中央治理分开，且中央治理始终可访问。YAYIN/12 曾短暂地将规模默认指向 kasaKok；这破坏了使用分离根目录的宿主。YAYIN/13 恢复了中央默认值。

我们不保证的事项

• 不提供云同步。 保险库就是你指定的文件。不会上传任何内容。
• 不自动合并。 两个写入方，两个文件。需要你自行协调。
• 此版本不支持删除。 可以退役；擦除功能将在后续提供。
• 不自动检测冲突。 相互矛盾的事实可以并存，直到有人另行处理。
• 不提供托管服务。 npx tugra 是本地 stdio 进程。

此包并非作为 SaaS 发布。这里没有价格表。

要求

• Node.js 20 或更高版本。这是支持策略，而非技术底线：该包在 CI 中针对 20 和 22 进行了测试，也能在 18 上运行——但 18 已结束生命周期，因此我们不提供支持。
• 由你拥有的保险库目录

主题映射（可选）

<vault>/_konu-haritasi.json — harita、alt_kirilim 和 stem 中的 { "desen", "bayrak", "konu" } 规则。若文件缺失，映射为空：未知文本会回退到 kurum.genel 或 dunya.<world>.genel。格式错误或过长的模式会被跳过并记录日志。此包不附带公司分类体系。

许可证

Apache-2.0。参见 LICENSE 和 NOTICE。

营销页面位于 ../site/（在该目录中运行 npm run preview）。此包不会部署该页面。

兼容性：如果未设置英文名称，TUGRA_KASA、TUGRA_AKIS、TUGRA_YETKI（以及较早的 TALAMUS_* / MULTI_* 名称）仍可作为备用项使用。