Nopal Coprocessor

Captures the intent behind your commits as a knowledge graph — enabling causal traceability, intelligent project exploration, and MCP-powered graph queries. Powered by NopalDB.

What is it?

Nopal Coprocessor is a semantic code journal that records the why behind your code changes — not just the what. Every semantic commit captures your rationale, the affected files, classes, and functions, and stores them as interconnected nodes in a knowledge graph.

Over time, your project builds a navigable map of decisions, enabling questions like:

• "Why was this module refactored?"
• "Which commits touched this class in the last month?"
• "What's the causal chain that led to this architecture?"

Features

Semantic Commits

Two ways to record semantic commits:

Via Git — use the prefixes arch:, causal:, or amend: in your commit message:

git commit -m "arch: replaced polling with event-driven for sub-ms latency"
git commit -m "causal: root cause was off-by-one in pagination offset"
git commit -m "amend: updated prior decision after edge case discovery"

The installed post-commit hook automatically intercepts these prefixes, extracts affected files, and records the event in the knowledge graph.

Via Command Palette — run Nopal: Semantic Commit for richer extraction:

• Rationale — your intent, in your own words
• JIT entity extraction — classes, functions, and modules detected via LSP from the active document
• Git context — commit hash, branch, and diff metadata

Graph Explorer

Visualize your project's knowledge graph directly in the editor. See how commits, files, and entities are connected.

NQL Queries

Query your knowledge graph using NopalDB's query language (NQL):

find e.rationale, e.commit_hash from (e:EpisodicEvent) order by e.timestamp desc limit 10

Project Indexing (Cold Start)

When the extension connects to a new, empty knowledge graph, it automatically scans your workspace to populate the graph with your project's structural topology (files, classes, functions, and modules).

You can also trigger this manually after a major refactor by running Nopal: Index Project Structure.

Audit Reports & Subgraph Export

Generate causal governance reports (ADRs) from your knowledge graph — optimized for both humans and AI agents.

For efficient graph exploration, the coprocessor exposes a full navigation toolkit: get_node, get_neighbors, find_path, run_pagerank, and similar_nodes for focused traversal — plus export_context_arrow for bulk subgraph export via mmap when you need the full picture in a single call.

Background Enrichment

The coprocessor monitors git activity and automatically enriches pending commits in the background via a git hook.

Autonomous Agent Integration

Nopal Coprocessor is designed to act as the shared memory layer for autonomous coding agents (e.g., Antigravity, Cline, Cursor).

To respect your workspace integrity, agent-specific instructions are not injected automatically. To enable neurosymbolic capabilities for your AI agents, initialize the integration via the command palette:

Nopal: Install AI Agent Rules

This wizard allows you to select your preferred agent environment and generates the appropriate instructional constraints (e.g., .cursorrules, .agents/skills/nopal-coprocessor/SKILL.md, or a standard AI.md).

File Rename Sync

When you rename files in the editor, the knowledge graph is updated automatically to reflect the new paths.

Requirements

You need the nopaldb-mcp binary installed. Choose one:

Homebrew (macOS/Linux):

brew install Anxious-Mind-Group/nopaldb/nopaldb

Build from source:

git clone https://github.com/sharop/nopaldb
cd nopaldb
cargo build --release -p nopaldb-mcp

The extension auto-detects the binary from your system PATH (Homebrew) or from target/release/ in your workspace (source builds).

Commands

Settings

How it works

┌─────────────────────┐     MCP/SSE      ┌──────────────┐
│  Nopal Coprocessor  │ ◄──────────────► │  nopaldb-mcp │
│  (Editor Extension) │                  │  (MCP Server) │
└─────────────────────┘                  └──────┬───────┘
        │                                       │
   Semantic Commits                        NopalDB Graph
   JIT Indexing                            (Knowledge Graph)
   Graph Explorer                          ACID Transactions

1. The extension spawns or connects to the nopaldb-mcp server via SSE.
2. Semantic commits and project indexing send structured data through MCP tool calls.
3. All data is persisted in a local NopalDB graph database with ACID transactions.
4. The graph can be queried, visualized, and exported at any time.

License

MIT