Neuroloom

Claude Code starts every session from scratch - context is lost and the CLAUDE.md grows out of date faster than your README.md. This plugin connects Claude to Neuroloom — the memory engine for agentic coding. Every tool use is captured, relationships between decisions are tracked, and each new session starts with the full graph of your past work.

Using Cursor, Codex or any other coding agent? See the MCP Integration guide for the .mcp.json setup path.

---

Prerequisites

• Claude Code
• python3 >= 3.11

---

Installation

Install from Claude Code Marketplace (recommended)

1. Add the Endless Galaxy Studios marketplace:

   /plugin marketplace add endless-galaxy-studios/claude-plugins
   

2. Install Neuroloom:

   /plugin install neuroloom@endless-galaxy-studios
   

3. Configure your API key:

   /plugin
   Navigate to Installed --> neuroloom Plugin --> Configure options
   

4. Restart Claude Code, then verify:

   /neuroloom:status
   

To upgrade:

/plugin marketplace update endless-galaxy-studios

Install via pip

1. Install the MCP server:

   pip install neuroloom-mcp
   

2. Install the plugin:

   neuroloom-mcp install-plugin
   

3. Restart Claude Code.

4. Set your API key with /plugins configure neuroloom in Claude Code.

To upgrade:

To update the MCP server:

pip install --upgrade neuroloom-mcp

To update the plugin:

neuroloom-mcp install-plugin --force

---

Post-Installation

1. Add .neuroloom.db* to your project's .gitignore — the file holds your project's API key and session state, and lives in your project root no matter what installation method you use. Write it with the trailing *: SQLite also creates .neuroloom.db-wal and .neuroloom.db-shm next to the database, and a bare .neuroloom.db entry does not cover them. Outside CI mode, SessionStart adds the .neuroloom.db* line for you if it is missing; in CI mode it never edits .gitignore.

2. Initialize workspace memory:

   /neuroloom:init
   

   This crawls your codebase in four phases: maps the directory structure, asks a question about priorities, stores 20–40 structured seed memories across your modules, and seeds the code graph with file-level symbols. After init, memory_search is useful from the first query.

What the plugin does

• Context injection — before Claude reads a file, Neuroloom injects relevant memories (prior decisions, known gotchas, related patterns) directly into the conversation. Before Glob/Grep searches, it nudges Claude toward relevant memories it might want to query.
• Observation capture — every tool use is captured and sent to Neuroloom in the background. When the session ends, Neuroloom extracts structured memories and discovers relationships between them.
• Code graph sync — when you edit TypeScript or Python files, the plugin parses the file's structure (functions, classes, imports) via tree-sitter and syncs it to Neuroloom (support for other languages coming soon).
• MCP tools — Claude can query Neuroloom directly via memory_search, memory_explore, memory_store, memory_by_file, and others.

Zero-touch bootstrap

neuroloom-codeweaver — the code graph sync package — is installed automatically on first SessionStart. No manual install step is needed after a marketplace install.

On the first session after installing the plugin, SessionStart creates a .venv in ${CLAUDE_PLUGIN_DATA} (the persistent per-plugin data directory; in a development clone with no CLAUDE_PLUGIN_DATA, inside the plugin directory) and installs neuroloom-codeweaver into it in a background thread. If venv creation fails (for example, on macOS where the system Python has ensurepip stripped), it falls back to a --user install. A --user install lands in ~/.local/lib/... on POSIX or %APPDATA%\Python\ on Windows — visible to any code running under that interpreter, not isolated to the plugin venv.

If both paths fail, a banner appears in the Claude Code transcript explaining how to install manually:

python3 -m pip install neuroloom-codeweaver

Offline or air-gapped environments: Set NEUROLOOM_CODEWEAVER_OFFLINE to any non-empty value to skip the install attempts (the venv, pip install and the --user fallback). The banner will not fire. This does not turn off the update check: when neuroloom-codeweaver is already importable, SessionStart can still ask PyPI for the latest version and run pip install --upgrade if a newer one exists, so on a machine with no route to PyPI the check fails quietly and changes nothing.

In CI mode you do not need this variable: CI mode skips the codeweaver install and the upgrade check outright, and never touches PyPI or pip.

export NEUROLOOM_CODEWEAVER_OFFLINE=1

How It Works

All hooks are Python modules in pyhooks/, launched via run_hook.py. When a .venv exists in ${CLAUDE_PLUGIN_DATA} (or, as the development fallback, inside the plugin directory), hooks run inside it; when it does not, the system Python that invoked the launcher is used as a fallback so all non-codeweaver hooks still run. (CI mode never looks for a venv; see CI mode.) State is stored in a single SQLite database (.neuroloom.db) using WAL mode for concurrent access.

Where the database lives. In every mode, every hook takes its state from one project root: CLAUDE_PROJECT_DIR when Claude Code sets it (it stays on the directory the session started in, even after the agent runs cd), otherwise the hook process's own working directory. The API key, the session row, the cache keys and the debounce state are all read from and written to <project root>/.neuroloom.db. A cd into a subdirectory no longer makes hooks look for a second database there.

This is the beginning of the README. Read the rest at the original. Read the full README ↗