Simba

"Remember who you are." — Mufasa

A unified Claude Code plugin that combines semantic memory, CLAUDE.md rule enforcement, neuro-symbolic logic (Z3 + Datalog), and project-aware search into a single Python package, with Codex skill support for onboarding workflows.

Quick Start

# Install (editable — picks up source changes immediately)
uv tool install -e /path/to/simba

# Register hooks in Claude Code
simba install

# Done. Start a Claude Code session and everything auto-starts.

Installation

Prerequisites

• Python 3.12+
• uv for dependency management

Install from source (editable)

Recommended during development. Source changes take effect immediately.

git clone git@github.com:mahmoudimus/simba.git
cd simba
uv tool install -e .

The simba binary is installed to ~/.local/bin/simba (ensure this is on your PATH).

Install from git

uv tool install git+https://github.com/mahmoudimus/simba.git

Register hooks

simba install             # Register hooks + skills in current project
simba install --global    # Register hooks + skills globally (~/.claude/)
simba install --remove    # Remove hooks and skills

Codex Skill

This repo now includes a Codex-native skill (simba-onboard) and an installer command:

simba codex-install           # Install bundled Codex skills to $CODEX_HOME/skills
simba codex-install --remove  # Remove bundled Codex skills
simba codex-status            # Check daemon health + pending extraction
simba codex-extract           # Print extraction prompt for latest transcript
simba codex-recall "<query>"  # Query semantic memory via /recall
simba codex-finalize          # Run end-of-task signal/error checks
simba codex-automation        # Print a suggested Codex automation directive

Default install path:

• ${CODEX_HOME:-$HOME/.codex}/skills/simba-onboard/
• ${CODEX_HOME:-$HOME/.codex}/skills/simba-codex-lifecycle/

Ask Codex to use:

• simba-onboard for project instruction onboarding
• simba-codex-lifecycle to enforce codex-status / codex-extract / codex-finalize

Workflow

Setting Up a New Project

cd ~/src/my-project

# 1. Install simba hooks and skills into this project
simba install

# 2. In Claude Code, run the onboarding skill
/simba-onboard

The /simba-onboard skill walks you through:

• Reading all your project's markdown files (CLAUDE.md, AGENTS.md, .claude/**/*.md)
• Extracting key instructions into categories (constraints, build commands, environment, etc.)
• Generating .claude/rules/CORE_INSTRUCTIONS.md with SIMBA marker sections
• Wiring references into CLAUDE.md and AGENTS.md

Day-to-Day Usage

Once installed, simba works automatically via hooks. No manual steps needed during normal Claude Code sessions.

What happens on each session:

1. SessionStart — memory daemon auto-starts, tailor context injected, project stats shown
2. Every prompt — relevant memories recalled, core rules reinforced, search context injected
3. Every tool call — vector DB queried based on Claude's thinking; context-low warning when approaching compaction
4. Session end — transcript exported for learning extraction; error patterns captured

Managing Core Instructions

SIMBA markers (<!-- BEGIN SIMBA:name -->) define sections in markdown files that simba can discover, audit, and update.

# See what markers exist in your project
simba markers list

# Check marker health (stale content, user-defined markers)
simba markers audit

# Update managed sections with latest templates
simba markers update

# Convert old markers (NEURON:*, CORE, etc.) to SIMBA format
simba markers migrate

Edit .claude/rules/CORE_INSTRUCTIONS.md directly to refine rules. Marker sections are preserved — simba only touches content between its own <!-- BEGIN SIMBA:* --> tags.

Configuring Simba

# See all configurable settings
simba config list

# Adjust memory recall sensitivity
simba config set memory.min_similarity 0.40

# Use a custom port for the daemon
simba config set memory.port 9000

# Set a global default (applies to all projects)
simba config set --global memory.max_results 5

# View effective config (local > global > defaults)
simba config show

Global vs Per-Project Install

Per-project is the default. Use global when you want simba active in every Claude Code session regardless of project.

What It Does

Simba hooks into six Claude Code lifecycle events to provide persistent context across sessions:

Memory Daemon

FastAPI server backed by LanceDB for vector storage. Supports two embedding backends.

In-process mode (default)

Loads a GGUF model via llama-cpp-python. No external services needed. The model (~81 MB) auto-downloads from Hugging Face on first startup.

simba server                                    # Default — auto-downloads nomic-embed-text
simba server --model-path /path/to/model.gguf   # Use a local GGUF file
simba server --n-gpu-layers 0                   # CPU-only mode
simba server --port 9000 --db-path /path/to/db  # Custom port and database

External server mode

Delegates embedding to an external OpenAI-compatible server.

simba server --embed-url http://localhost:8080

Works with llama-cpp-python server, vLLM, text-embeddings-inference, or any OpenAI-compatible endpoint.

Endpoints

Neuron — Neuro-Symbolic Logic Server

Neuron is an MCP (Model Context Protocol) server that gives Claude Code access to formal verification tools (Z3 theorem prover, Souffle Datalog) and a truth database.

Setup

# Register the MCP server with Claude Code
simba neuron install

MCP Tools

Neuron exposes 4 tools via the Model Context Protocol:

Truth Database

A local SQLite database (.simba/simba.db, proven_facts table) that stores proven facts as subject-predicate-object triples with their proof text. Claude queries this before making assumptions about the codebase.

# Run the MCP server directly
simba neuron run --root-dir .

Orchestration — Agent Dispatch Server

Orchestration is an MCP server for async agent dispatch, status tracking, and process management.

Setup

# Register the MCP server with Claude Code and bootstrap agent definitions
simba orchestration install

# With hot-reload proxy (useful during development)
simba orchestration install --proxy

This registers Orchestration as an MCP server in .claude/settings.json and creates agent definition files in .claude/agents/.

MCP Tools

Orchestration exposes 4 tools via the Model Context Protocol:

Agent Management

# Update agent status (called by subagents, not users)
simba orchestration status <ticket_id> completed
simba orchestration status <ticket_id> failed -m "error message"

Managed Sections

Orchestration manages auto-updated sections in CLAUDE.md and agent definition files using <!-- BEGIN SIMBA:name --> markers. These sections contain tool instructions, workflows, and agent-specific guidance.

# Update managed sections in CLAUDE.md and agent files
simba orchestration sync

# Inject markers into agent definition files
simba orchestration agents --inject

# Update content in existing markers
simba orchestration agents --update

Context-Low Early Warning

The PreToolUse hook monitors the session transcript file size. When it exceeds a configurable threshold (default 4 MB), it injects a one-time <context-low-warning> into Claude's context recommending that it summarize its current work state before auto-compact triggers.

This gives Claude time to document progress, pending tasks, and branch context so the pre-compact transcript export captures a clean snapshot for learning extraction.

Sync Pipeline

Automatic indexing and learning extraction from project files and session transcripts.

simba sync run                              # Full cycle: index + extract
simba sync schedule --interval 300          # Run every 5 minutes
simba server --sync-interval 300            # Start daemon with periodic sync

The sync pipeline:

1. Index — scans project files and builds the search database
2. Extract — processes exported transcripts and stores learnings in semantic memory

Sync can also be triggered via POST /sync on the daemon, which the SessionStart hook does automatically.

Guardian — CLAUDE.md Rule Enforcement

Extracts content between <!-- BEGIN SIMBA:core --> tags from CLAUDE.md and injects it as context on every prompt. On session stop, checks whether Claude's response contains the [✓ rules] compliance signal.

Mark critical rules in your CLAUDE.md:

## Critical Constraints
<!-- BEGIN SIMBA:core -->
- Never delete files without confirmation
- Always run tests before committing
<!-- END SIMBA:core -->

These rules are reinforced on every prompt regardless of context window state.

Markers CLI

Discover, audit, update, and migrate SIMBA markers across .md files.

simba markers list                    # Scan for all markers, show file/section/line
simba markers audit                   # Find unused, orphaned, or stale sections
simba markers update                  # Bulk-update all markers with current templates
simba markers show completion_protocol # Print a section's template content
simba markers migrate --path /project # Convert NEURON:*, CORE, etc. to SIMBA format
simba markers migrate --dry-run       # Preview without modifying files

The migrate command converts non-SIMBA markers (<!-- BEGIN NEURON:name -->, <!-- CORE -->, bare <!-- BEGIN X -->) to proper <!-- BEGIN SIMBA:name --> format, preserving body content.

Skills

Skills are slash-command invocable capabilities defined in skills/. They run as forked agents with restricted tool access.

/simba-onboard — Project Onboarding

Interactive skill that analyzes your project's markdown files and generates consolidated core instructions with SIMBA markers:

1. Reads CLAUDE.md, AGENTS.md, and all .claude/**/*.md files
2. Extracts key instructions into categories (constraints, build commands, environment, code style, workflow, agent rules)
3. Generates .claude/rules/CORE_INSTRUCTIONS.md with SIMBA marker sections
4. Presents content for user verification before writing
5. Wires references into CLAUDE.md and AGENTS.md

# In Claude Code, after simba install:
/simba-onboard

The skill is automatically installed by simba install. It creates a structure similar to:

# .claude/rules/CORE_INSTRUCTIONS.md
<!-- BEGIN SIMBA:constraints -->
## Critical Constraints
- Never delete files without confirmation
<!-- END SIMBA:constraints -->

<!-- BEGIN SIMBA:build_commands -->
## Build & Test
make && make test
<!-- END SIMBA:build_commands -->

/memories-learn — Extract Learnings from Transcripts

Automatically triggered after context compaction:

1. PreCompact hook exports the session transcript to ~/.claude/transcripts/{sessionId}/ with status: "pending_extraction"
2. SessionStart hook on the next session detects the pending export and injects extraction instructions
3. A memory-extractor agent reads the transcript, extracts 5-15 learnings, and POSTs each to the memory daemon (/store)

Memory types: GOTCHA, WORKING_SOLUTION, PATTERN, DECISION, FAILURE, PREFERENCE

Can also be invoked manually with /memories-learn.

/memories-sanitize — Review and Clean Up Memories

Manual skill for auditing the memory database:

1. Lists all memories via GET /list
2. Identifies invalid, outdated, superseded, or misleading entries
3. Deletes bad memories via DELETE /memory/{id}
4. Optionally stores corrected replacements

Use when memory quality degrades or after bulk extraction sessions.

Memory Pipeline Flow

Session ends → PreCompact exports transcript
    → Next session: SessionStart detects pending extraction
    → memory-extractor agent reads transcript.md
    → POSTs learnings to /store (semantic memories in LanceDB)
    → simba sync extract converts memories to proven facts (SQLite)
    → UserPromptSubmit + PreToolUse hooks recall memories on future prompts

Project Search

Per-project session memory and semantic search. Combines SQLite FTS5 with QMD semantic search.

simba search init                    # Initialize project memory
simba search add-session "summary" '["files"]' '["tools"]' "tags"
simba search add-knowledge "area" "description" "details"
simba search add-fact "fact text" "category"
simba search search "query"          # Search project memory
simba search context "query"         # Get combined RAG context
simba search recent 5                # View recent sessions
simba search stats                   # Show statistics

Optional external tools for enhanced search:

• ripgrep — fast file discovery
• fzf — fuzzy filtering for file suggestions
• qmd — semantic markdown search

CLI Reference

simba install                 Register hooks + skills (project-local)
simba install --global        Register hooks + skills (~/.claude/)
simba install --remove        Remove hooks and skills
simba codex-install           Install bundled Codex skills (~/.codex/skills)
simba codex-install --remove  Remove bundled Codex skills
simba codex-status            Check daemon health + pending extraction
simba codex-extract           Print extraction prompt for latest transcript
simba codex-recall <query>    Query semantic memory via /recall
simba codex-finalize          Run end-of-task signal/error checks
simba codex-automation        Print a suggested Codex automation directive
simba server [opts]           Start memory daemon
simba neuron run              Run neuron MCP server (truth/verify)
simba orchestration install   Register orchestration MCP server
simba orchestration run       Run orchestration MCP server
simba orchestration proxy     Run via hot-reload proxy
simba orchestration sync      Update managed sections
simba orchestration agents    Manage agent definition files
simba orchestration status    Update agent task status
simba config list              List all configurable sections
simba config get <key>         Print effective value (e.g. memory.port)
simba config set <key> <val>   Set a config value (local)
simba config set --global ...  Set a config value (global)
simba config reset <key>       Remove a local override
simba config show              Dump full effective config
simba config edit [--global]   Open config.toml in $EDITOR
simba markers list             List all SIMBA markers in .md files
simba markers audit            Compare markers vs MANAGED_SECTIONS
simba markers update           Update markers with current templates
simba markers show <section>   Print raw template for a section
simba markers migrate          Convert non-SIMBA markers to SIMBA format
simba search <cmd>            Project memory operations
simba sync run           Run a full sync cycle (index + extract)
simba sync index         Index project files only
simba sync extract       Extract learnings from transcripts only
simba sync status        Show sync pipeline status
simba sync schedule      Run sync on a periodic interval
simba stats              Token economics and project statistics
simba hook <event>       Run a hook (called by Claude Code, not users)

Development

git clone git@github.com:mahmoudimus/simba.git
cd simba
uv sync

# Run tests
uv run pytest                     # all tests (~516)
uv run pytest -x                  # stop on first failure
uv run pytest -k "test_name"      # specific test

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run ruff check --fix src/

# Type check
uv run pyrefly check

Code Style

• Module-level imports only: import X then X.Y, not from X import Y
• Exemptions: from __future__ import annotations, from typing import TYPE_CHECKING
• pathlib.Path over os.path

Pre-commit Hooks

uv run pre-commit install

Data Storage

All project-level data lives under a single .simba/ directory in the project root:

.simba/
  simba.db             SQLite — proven facts, activities, reflections, agent runs, sync watermarks
  memory/              LanceDB vector database (semantic memories)
  search/              Search activity log
  tailor/              Error reflection journal (JSONL)
  config.toml          Local configuration overrides (optional)

This directory is gitignored. The embedding model cache lives in ~/.cache/huggingface/hub/.

Unified Configuration

All simba settings are configurable via TOML files with git-style scoping:

~/.config/simba/config.toml     # --global (user-wide defaults)
.simba/config.toml              # local (project-specific overrides)

Precedence: local > global > code defaults. CLI arguments still override config file values.

simba config list                              # Show all sections + fields
simba config get memory.port                   # Print effective value
simba config set memory.min_similarity 0.40    # Write to local config
simba config set --global memory.port 9000     # Write to global config
simba config reset memory.min_similarity       # Revert to default
simba config show                              # Dump full effective config

Configurable Sections

New config sections can be added by decorating a dataclass with @simba.config.configurable("section_name").

Configuration Reference

Memory Daemon

Neuron

Orchestration

License

MIT