neuralscape

Neuralscape - Agentic Memory Layer

A production-grade memory system for AI coding assistants and personal agents. Neuralscape gives any LLM-powered agent persistent, structured memory across sessions and projects — remembering user preferences, project conventions, technical decisions, and learned facts.

Built on mem0 (vector storage + LLM deduplication) and Graphiti (temporal knowledge graph), exposed via REST API and MCP server. Memory writes are processed asynchronously by background workers via ARQ + Redis.

Looking for the comprehensive reference? See docs/neuralscape/ for 12 pages covering architecture, schemas, plugin internals, deployment, and more. Start at 00-overview.md or jump straight to 01-getting-started.md for the full setup walkthrough.

Prerequisites

• Python 3.10+ and uv (for local development)
• Docker + Docker Compose (for containerized deployment)
• Google API key with Gemini access (for LLM extraction + embeddings)
• Neo4j — included in Docker Compose, or use Neo4j Desktop for local dev
• Redis — included in Docker Compose, or run locally
• Qdrant — included in Docker Compose as a server, or run locally

Quick Start (Docker)

# 1. Copy env template and add your Gemini API key
cp .env.example .env
# Edit .env: set GOOGLE_API_KEY=your-key

# 2. Start the full stack
docker compose up --build -d

# 3. Verify
docker compose ps
# Should show: neo4j, redis, qdrant, neuralscape, neuralscape-worker

curl http://localhost:8199/health
# → {"status":"ok","service":"neuralscape-memory","checks":{"redis":"ok","vector_store":"ok","graph_store":"ok"}}

# 4. Test async memory storage
curl -X POST http://localhost:8199/v1/memories/raw \
  -H "Content-Type: application/json" \
  -d '{"content": "Prefers dark mode", "user_id": "test", "category": "preference"}'
# → {"status":"accepted","task_id":"...","poll_url":"/v1/memories/status/..."}

# 5. Install the Claude Code / Cowork plugin (optional but recommended)
# From inside Claude Code:
#   /plugin marketplace add ehfazrezwan/neuralscape
#   /plugin install neuralscape@neuralscape-plugins
# Cowork: Customize → Browse plugins → Install. Same catalog, GUI flow.
# The plugin will prompt for your service URL, API key (optional), and user_id.

# Stop with: docker compose down

Local Setup (without Docker)

# Start Redis and Qdrant (via Docker or locally)
docker run -d --name redis -p 6379:6379 redis:7-alpine
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant:v1.13.2

cd neuralscape-service

# Create .env file
cat > .env << 'EOF'
GOOGLE_API_KEY=your-gemini-api-key
NEO4J_URI=neo4j://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-neo4j-password
NEO4J_DATABASE=memory
QDRANT_URL=http://localhost:6333
EOF

# Install dependencies
uv sync

# Start the ARQ worker (terminal 1)
uv run arq worker.WorkerSettings

# Start the API server (terminal 2)
uv run python main.py
# → Listening on http://0.0.0.0:8199

# Run unit tests (no external services needed)
uv run pytest tests/test_service.py -v

# Run integration tests (requires all services running)
uv run pytest tests/test_async_pipeline.py -v -s

Claude Code / Cowork Plugin

The neuralscape plugin gives Claude Code automatic, persistent memory: lifecycle hooks plus nine user-facing slash commands (plus an internal compile-observations helper the hooks/capture invoke) plus the eight Neuralscape MCP tools auto-wired on install.

Claude Cowork: Cowork does not run plugin hooks (#27398), so the automatic inject/capture loop below does not fire there. Cowork is supported via a remote MCP OAuth connector plus a standing-context "memory protocol" that drives recall/capture through the MCP tools. See COWORK.md — that is the supported Cowork path, not this hook-based one.

How It Works

[Claude Code or Cowork]
    ↓ SessionStart hook (sync — pulls context from /v1/context/, injects as additionalContext)
    ↓ Stop hook        (async — flushes new turns, commits offset, triggers compile)
[neuralscape-plugin/]  ← TypeScript plugin (auto-detects Claude Code / Cowork / OpenClaw / generic)
    ↓ HTTP calls
[neuralscape-service/] ← Python service (extraction, storage, graph, vault dual-write)