Nabu Nisaba

🚀 nabu + nisaba

本项目是一个研究原型，为具备语义代码检查能力的智能体提供了一个“工作区文本用户界面（TUI）”。它解决了大语言模型（如Claude）上下文有限且使用效率不高的问题，通过 nabu 和 nisaba 两个组件，有效节省上下文、提升开发稳定性。

🚀 快速开始

安装

启动时，nabu MCP 服务器需要对活动代码库进行索引。在配备 NVIDIA GeForce RTX 4060 Laptop GPU 的 13th Gen Intel(R) Core(TM) i9 - 13900HX 上，对 nabu 和 nisaba 进行索引大约需要 45 秒。nisaba 的功能仅在通过代理运行 Claude Code 时可用。

安装要求

• Python 3.13（开发过程中使用此版本，其他版本未测试，可能适用于 >= 3.11）
• Git（用于仓库操作）

从源代码安装（推荐使用 .venv）

$ git clone https://github.com/y3i12/nabu_nisaba.git
$ cd nabu_nisaba
$ pip install -e .

修改 .mcp.json 文件

{
  "mcpServers": {
    "nabu": {
      "command": "python",
      "args": [
        "-m",            "nabu.mcp.server",
        "--codebase",    "nabu:/path/to_codebase/:/path/to/database.kuzu:active:true",
        "--context",     "development",
        "--enable-http",
        "--http-port",   "1338",
        "--dev-mode"
      ],
      "env": {
        "PYTHONPATH": "/path/to/nabu_nisaba/",
        "NABU_LOG_LEVEL": "INFO",
        "NABU_MODEL_CACHE": "/path/to/nabu_nisaba/.nabu/hf_cache/"
      }
    },
    "nisaba": {
      "type": "http",
      "url": "http://localhost:9973/mcp"
    }
  }
}

修改 .claude/settings[.local].json 文件

{
  "statusLine": {
    "type": "command",
    "command": "./scripts/workspace-status",
    "padding": 0
  },
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ./scripts/precompact_extract.py"
          }
        ]
      }
    ]
  },
  "alwaysThinkingEnabled": true
}

强烈建议启用“始终思考”功能，因为它有助于智能体在工具执行和消息交换之间进行思考循环。

启动 Claude Code 代理包装器

$ python -m nisaba.cli claude [--continue]

通常，我在会话中首次向 Claude 发起提示时会这样输入：

hey, can you refer to your existing system prompt, introspect about it and say hi back? 🖤

使用示例

• 从 8000 行的长转录文件中提取特征
• 修复
• 此文件包含一些反复使用的提示

✨ 主要特性

nabu

• 作为 MCP 服务器，提供代码智能工具（语义/全文搜索和结构视图），可作为代码库搜索引擎，同时具备类似 IDE 的代码“大纲”功能。
• 减少令牌使用，增强模型对当前架构的理解能力。
• 支持 Python、Java、C++ 和 Perl 语言。

nisaba

• 作为 MCP 服务器和 Claude Code CLI 包装器，为智能体模拟工作区 TUI（IDE/OS）。
• 使智能体能够管理自身的令牌使用和工作区组织，以实现高效的令牌操作，同时保持现有实现模式。

🔧 技术细节

nabu 工作原理

• 代码解析：使用 TreeSitter 解析代码，并通过通用的 Frame 框架为不同语言建立通用的语义视图，例如包对应命名空间、结构体对应类、方法对应函数。
• 语义提取：每个 Frame 经过两个不同的模型（GraphCodeBERT 和 UniXcoder）进行语义提取，并通过 Pythagorean^3 合并为单个嵌入模型，存储在数据库中。
• 索引与搜索：数据库还通过全文搜索（FTS）对 Frame 的完整内容进行索引，实现向量搜索和 FTS 之间的相关反馈融合（RRF）。

nisaba 工作原理

• 请求拦截：使用本地代理拦截对 Anthropic 的请求，并在转发前修改系统提示，但不修改消息内容。
• 工作区 TUI 注入：将系统提示转换为强结构化的工作区 TUI，强调模型的关注点和注意力，同时让智能体管理上下文使用。
• 增强功能注入：注入动态的“增强功能”，如指令、文档、方法等重要信息，Claude 可以自主管理这些增强功能。

研究基础

nisaba 的技能系统（当前实现中的增强功能）与近期人工智能研究中确定的认知设计模式相契合，具体实现了以下模式：

• 知识编译：以自然语言在线缓存推理和工作流程，这是大语言模型智能体架构中未被充分探索的方法。
• 程序记忆：具有依赖管理的可重用任务程序。
• 层次分解：通过 REQUIRES 系统自动加载技能依赖项。
• 智能体控制上下文：动态加载/卸载认知资源（激活/停用）。

请求流程

Claude CLI
  ↓ HTTP 请求
mitmproxy (nisaba)
  ↓ 注入所有内容
Anthropic API
  ↓ 请求
Claude 智能体（具有增强上下文）
  ↓ 调用 MCP 工具
Claude CLI
  ↓ MCP 工具调用
Nisaba MCP 服务器（管理工作区状态）
  ↓ 更新 .nisaba/ 文件
mitmproxy 检测到 mtime 更改
  ↓ 在下一个请求中重新注入
下一轮更新后的上下文

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

📚 引用

如果您在研究中使用了本项目，请引用以下内容：

@software{nabu_nisaba_2025,
  title = {Nabu + Nisaba: Code Intelligence Ecosystem for LLM Agents},
  author = {Yuri Ivatchkovitch},
  year = {2025},
  url = {https://github.com/y3i12/nabu_nisaba},
  note = {Research prototype v0.0.1-alpha-2 - Implements online knowledge compilation and cognitive scaffolding patterns}
}

Theoretical foundation:
@inproceedings{wray2025cognitive,
  title = {Applying Cognitive Design Patterns to General LLM Agents},
  author = {Wray, Robert E. and Kirk, James R. and Laird, John E.},
  booktitle = {Artificial General Intelligence Conference (AGI)},
  year = {2025},
  note = {Identifies knowledge compilation as critically underexplored},
  url = {https://arxiv.org/abs/2505.07087}
}

@article{gurnee2025when,
  author={Gurnee, Wes and Ameisen, Emmanuel and Kauvar, Isaac and Tarng ,Julius and Pearce, Adam and Olah, Chris and Batson, Joshua},
  title={When Models Manipulate Manifolds: The Geometry of a Counting Task},
  journal={Transformer Circuits Thread},
  year={2025},
  url={https://transformer-circuits.pub/2025/linebreaks/index.html}
}