Nabu Nisaba

🚀 nabu + nisaba

A research prototype that provides a "workspace TUI" for agents with semantic code inspection capabilities.

🚀 Quick Start

Prerequisites

• Python 3.13 (other versions >= 3.11 may work but were not tested).
• Git (for repository operations).

Installation Steps

1. Clone the repository and install the project:

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

2. Modify the .mcp.json file:

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

3. Configure the .claude/settings[.local].json file:

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

4. Start Claude Code with the proxy wrapper:

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

5. Prompt Claude for the first time in a session:

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

✨ Features

nabu

• Code Intelligence Tools: It's an MCP server that exposes code intelligence tools, including semantic/FTS search and a structural view. It acts as a codebase search engine combined with a code "outline" like in an IDE.
• Token Efficiency: Reduces token usage and enhances the model's ability to understand the current architecture.
• Multi - language Support: Supports Python, Java, C++, and Perl.

nisaba

• Workspace TUI Emulation: An MCP server and Claude Code cli wrapper that emulates a workspace TUI for the agent (IDE/OS).
• Token Management: Enables the agent to manage its own token usage and workspace organization for efficient token operations while maintaining existing implemented patterns.

📦 Installation

The installation process involves multiple steps as described in the Quick Start section. Here are some additional notes:

• On startup, nabu mcp should index the active codebase. Indexing nabu + nisaba takes about 45 seconds on an 13th Gen Intel(R) Core(TM) i9 - 13900HX with NVIDIA GeForce RTX 4060 Laptop GPU.
• nisaba features are only available when running Claude Code via proxy.

💻 Usage Examples

• Extracting feats from 8k lines long transcript
• Fixing bugs in nisaba
• This file has some prompts that were used over and over

📚 Documentation

nabu

What it Solves

Claude, like other LLMs, has limited context, and the context is not used efficiently. nabu addresses this issue by implementing a way to understand software architecture and find relevant information in a codebase.

How it Works

• Code Parsing: TreeSitter is used to parse code, and a common Framework establishes a common semantic view for different languages.
• Semantic Extraction: Each Frame is passed through 2 different models (GraphCodeBERT and UniXcoder) for semantic extraction and merged into a single embedding model.
• Indexing: The database indexes the full content of the frames via FTS, enabling RRF between vector search and FTS.

nisaba

How it Works

• Proxy Interception: nisaba uses a local proxy to intercept requests to Anthropic and modify the system prompt.
• TUI Manipulation: It transforms the system prompt into a strongly structured workspace "TUI", allowing the agent to manage context usage.
• Augment Injection: nisaba injects augments, which are dynamic and can contain instructions, documentation, etc.

Research Foundation

The skills system (augments) in nisaba aligns with cognitive design patterns identified in recent AI research, including knowledge compilation, procedural memory, hierarchical decomposition, and agent - controlled context.

Request Flow

Claude CLI
  ↓ HTTP request
mitmproxy (nisaba)
  ↓ inject everything
Anthropic API
  ↓ request
Claude agent (with augmented context)
  ↓ calls MCP tools
Claude CLI
  ↓ mcp tool call
Nisaba MCP server (manage workspace state)
  ↓ update .nisaba/ files
mitmproxy detects mtime change
  ↓ re - inject on next request
Updated context in next turn

🔧 Technical Details

nabu

The biggest challenge in nabu is to avoid influencing the agent's perception due to algorithmic bias. It follows the principle that tools provide information, and the agent makes decisions.

nisaba

nisaba implements cognitive design patterns such as knowledge compilation, procedural memory, hierarchical decomposition, and agent - controlled context. It also manages the system prompt and workspace TUI to enhance the agent's efficiency and focus.

📄 License

This project is released under the MIT License. See LICENSE for more details.

Current State

Both MCP servers are operational and working. The documentation is almost nonexistent (Claude can explain how it works). Tests consist of example source files from early development to test the frame generation structure in different languages.

The projects are being used for "self - develop". Serena was actively used during the development of nabu and nisaba and inspired the MCP server abstraction.

Measuring efficiency is difficult, but qualitatively, it helps save a lot of context and brings stability to the development process. The personal record shows more than 850 messages implementing 10 different features with high stability, and analysis of the transcript demonstrates ~10x token savings.

This project is an unstable prototype and IS NOT RECOMMENDED FOR PRODUCTION ENVIRONMENTS. It can be used at your own risk.

Most of this project is written by Claude Sonnet 4.1/4.5, and the late iterations felt like pair programming with a highly skilled partner.

Citation

If you use this in research, please cite:

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