⚡ lithium-kb: Structured Agent Knowledge Base & Neural Graph

npm version GitHub Packages GitHub Node.js Zero Dependencies MCP Compatible License: MIT

A high-performance structured project knowledge base generator, neural network memory visualizer, and Model Context Protocol (MCP) server for AI coding agents (Pi, Claude, Codex, Cursor, Windsurf).

📁 Structured Knowledge Hierarchy

Whenever lithium-kb is run, it organizes project memory into clean, modular knowledge categories:

your-project/
├── .lithium-kb/
│   ├── architecture/
│   │   └── overview.md             # Topology, entry points, service boundaries
│   ├── debug/
│   │   ├── quickstart-diagnostics.md # Resolved incidents & root-cause postmortems
│   │   └── ...
│   ├── tasks/
│   │   ├── initial-setup.md        # Active sprint tasks & acceptance criteria
│   │   ├── explorer-ui.md
│   │   └── ...
│   └── features/
│       ├── core-specs.md           # Detailed feature specifications
│       └── ...
├── .agentrules                     # Explicit AI agent navigation directives
└── PROJECT_KB.md                   # Compact global index (< 2KB)

⚡ Why Structured Knowledge Matters

Surgical Token Efficiency: When an agent works on a bug or task, it reads only .lithium-kb/tasks/<name>.md or .lithium-kb/debug/<name>.md instead of blindly traversing thousands of codebase lines.
Deterministic Context: Agents don't lose track of multi-step plans across sessions.
Interactive Neural Visualizer:
- File Explorer Sidebar: Collapsible category trees with directory rails, item count badges, and expand/collapse quick actions.
- Real-Time Impulses: Observe live memory hits, dynamic impulse animations, and token savings as agents query knowledge nodes.
Zero Dependencies: Pure Node.js standard library — zero install footprint, lightning fast.

📦 Installation & Quickstart

🚀 1-Command Setup (Auto-Configure All Agents & Editors)

Run this inside any project repository to initialize the knowledge structure and automatically configure MCP for Cursor, Claude Desktop, Windsurf, Zed, and VS Code (Cline / Roo Code):

npx @liulinnuha/lithium-kb init

Or run via interactive curl installer:

curl -fsSL https://raw.githubusercontent.com/liulinnuha/lithium-kb/main/bin/install.sh | bash

🛠️ CLI Commands

# Generate / Sync knowledge base (.lithium-kb/ and PROJECT_KB.md)
npx @liulinnuha/lithium-kb

# Open Neural Graph Web UI (port 3030)
npx @liulinnuha/lithium-kb --ui

# Auto-watch for file changes and sync live
npx @liulinnuha/lithium-kb --watch

# Launch MCP stdio server manually
npx @liulinnuha/lithium-kb --mcp

# Clean MCP configurations & legacy references from all IDEs
npx @liulinnuha/lithium-kb uninstall

# Completely purge MCP configurations and local .lithium-kb/ files
npx @liulinnuha/lithium-kb uninstall --purge

# Run interactive 1-line uninstaller wizard
curl -fsSL https://raw.githubusercontent.com/liulinnuha/lithium-kb/main/bin/uninstall.sh | bash

Global CLI Installation

Install globally on your machine to use lithium-kb anywhere:

npm install -g @liulinnuha/lithium-kb

# Then run anywhere:
lithium-kb --ui

🔌 Agent MCP Integration (Claude Desktop, Cursor, Pi)

Add this to your Claude Desktop config (claude_desktop_config.json) or Cursor MCP settings:

{
  "mcpServers": {
    "lithium-kb": {
      "command": "npx",
      "args": ["-y", "@liulinnuha/lithium-kb", "--mcp"]
    }
  }
}

📜 MCP Tools Exposed

Tool	Purpose
`get_project_memory`	Return compact architecture & symbol index (< 2KB).
`read_knowledge_doc`	Read targeted doc from `.lithium-kb/` (`category`, `filename`).
`write_knowledge_doc`	Persist new task note, debug postmortem, or feature spec.
`query_symbol_map`	Search exported functions, classes, and types across the repo.