Quickstart

The Neuroloom Claude Code plugin handles session lifecycle, context injection, and memory extraction automatically. You store knowledge by working — the plugin captures it.

Step 1: Install the plugin

Run this in any Claude Code session:

/plugin install neuroloom@endless-galaxy-studios

Claude Code fetches the plugin from the marketplace. You'll see a confirmation message when the install completes.

Step 2: Configure your API key

/plugins configure neuroloom

Claude Code prompts you for your API key. Paste the key from app.neuroloom.dev/settings/api-keys. The plugin stores it in your Claude Code settings — you won't be prompted again.

If you don't have a key yet, create a free account at app.neuroloom.dev. The free tier gives you cross-session memory with no time limit.

Step 3: Store your first memory

Ask Claude Code to store a memory directly:

Use memory_store to store a memory titled "SQLAlchemy async session configuration" with type "decision" and content "We use expire_on_commit=False on all session factories. Without this, accessing lazy-loaded relationships after commit raises DetachedInstanceError. Affects api/neuroloom_api/database.py."

You'll receive a response confirming the memory was stored, including its ID:

{
  "id": "mem-7f3a2c1b",
  "title": "SQLAlchemy async session configuration",
  "memory_type": "decision",
  "created_at": "2026-04-01T14:22:00Z"
}

Step 4: Search for it

Now retrieve it by meaning — not the exact title:

Use memory_search with query "session configuration database"

The memory appears in the results ranked by semantic similarity:

{
  "results": [
    {
      "id": "mem-7f3a2c1b",
      "title": "SQLAlchemy async session configuration",
      "memory_type": "decision",
      "score": 0.94,
      "summary": "expire_on_commit=False prevents DetachedInstanceError on lazy-loaded relationships after commit"
    }
  ]
}

You've confirmed that Neuroloom can find memories by meaning. A query about "session configuration database" matched a memory about expire_on_commit — because both describe the same concept.

Advanced: Direct MCP access

The plugin manages context injection automatically. If you also want to call MCP tools directly from a CLAUDE.md instruction or a custom workflow, add a .mcp.json in your project root:

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Or add it from the command line (user-scoped, not committed to the repo):

claude mcp add-json neuroloom -s user \
  '{"type":"http","url":"https://mcp.neuroloom.dev/mcp","headers":{"Authorization":"Bearer nl_your_api_key_here"}}'

The REST API gives you direct access to every Neuroloom operation. Use it from any language, CI pipeline, or tool that can make HTTP requests.

Step 1: Get your API key

Create a free account at app.neuroloom.dev, then navigate to app.neuroloom.dev/settings/api-keys to create your first API key.

Step 2: Set environment variables

export MEMORIES_API_TOKEN="nl_your_api_key_here"
export MEMORIES_WORKSPACE_ID="ws_your_workspace_id_here"

Your workspace ID is visible on the dashboard home page. Every API call is scoped to a workspace — memories stored in one workspace are not visible from another.

Step 3: Store a memory

curl -X POST https://api.neuroloom.dev/api/v1/memories/store \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'"$MEMORIES_WORKSPACE_ID"'",
    "title": "SQLAlchemy async session configuration",
    "memory_type": "decision",
    "narrative": "We use expire_on_commit=False on all session factories. Without this, accessing lazy-loaded relationships after commit raises DetachedInstanceError. Affects api/neuroloom_api/database.py.",
    "concepts": ["SQLAlchemy", "session management", "async patterns"],
    "source_files": ["api/neuroloom_api/database.py"],
    "importance_score": 0.9
  }'

import os
import httpx

token = os.environ["MEMORIES_API_TOKEN"]
workspace_id = os.environ["MEMORIES_WORKSPACE_ID"]

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/store",
    headers={"Authorization": f"Token {token}"},
    json={
        "workspace_id": workspace_id,
        "title": "SQLAlchemy async session configuration",
        "memory_type": "decision",
        "narrative": (
            "We use expire_on_commit=False on all session factories. "
            "Without this, accessing lazy-loaded relationships after commit "
            "raises DetachedInstanceError. Affects api/neuroloom_api/database.py."
        ),
        "concepts": ["SQLAlchemy", "session management", "async patterns"],
        "source_files": ["api/neuroloom_api/database.py"],
        "importance_score": 0.9,
    },
)
print(response.json())

Expected response:

{
  "id": "mem-7f3a2c1b",
  "title": "SQLAlchemy async session configuration",
  "memory_type": "decision",
  "workspace_id": "ws_your_workspace_id_here",
  "created_at": "2026-04-01T14:22:00Z",
  "importance_score": 0.9,
  "embedding_status": "pending"
}

embedding_status: "pending" means the semantic embedding is being generated in the background. It typically completes within 2 seconds. Search works immediately for keyword matching; semantic similarity requires the embedding to complete.

Step 4: Search for it

curl -X POST https://api.neuroloom.dev/api/v1/memories/search \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'"$MEMORIES_WORKSPACE_ID"'",
    "query": "session configuration database",
    "limit": 5
  }'

import os
import httpx

token = os.environ["MEMORIES_API_TOKEN"]
workspace_id = os.environ["MEMORIES_WORKSPACE_ID"]

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/search",
    headers={"Authorization": f"Token {token}"},
    json={
        "workspace_id": workspace_id,
        "query": "session configuration database",
        "limit": 5,
    },
)
results = response.json()
for r in results["results"]:
    print(f"{r['score']:.2f}  {r['title']}")

Expected response:

{
  "results": [
    {
      "id": "mem-7f3a2c1b",
      "title": "SQLAlchemy async session configuration",
      "memory_type": "decision",
      "score": 0.94,
      "summary": "expire_on_commit=False prevents DetachedInstanceError on lazy-loaded relationships after commit",
      "match_type": "semantic"
    }
  ],
  "total": 1
}

The memory appears at the top with a 0.94 score. The query "session configuration database" matched the stored memory semantically — even though those exact words don't appear in the title or narrative.