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}
}