claude-sulcus

◆ Sulcus

Persistent, intelligent memory for AI agents. Sulcus gives your agents a real memory layer — vector + graph search, reactive triggers, cross-agent access control, and automatic classification via SIU.

• ⚡ Reactive triggers — on_store, on_recall, on_decay, on_threshold → auto-pin, boost, notify, webhook
• 🔍 Vector + graph search — HNSW index with FastEmbed (local) or pgvector (cloud); graph edges for related memories
• 🏠 Local-first — embedded PostgreSQL (pg-embed), runs entirely on your machine
• 🔒 Cross-agent ACL — namespace isolation and tenant-scoped keys; memories stay in the right hands
• 🤖 SIU classification — automatic memory type detection (episodic, semantic, preference, procedural, fact)
• 🔥 Heat-based decay — memories cool naturally over time; important ones stay hot (thermodynamic model, one of many mechanisms)
• 🔌 MCP native — works with Claude Code, OpenClaw, Cursor, and any MCP client
• ☁️ Cloud sync — optional CRDT sync to sulcus.ca (paid tier)

Quick Start

Install sulcus

# Homebrew (macOS/Linux)
brew install digitalforgeca/tap/sulcus

# npm (downloads pre-built binary)
npm install -g @digitalforgestudios/sulcus

# Or build from source (requires Rust)
cargo install sulcus

Connect to Claude Code

Recommended: Full plugin (hooks + MCP + auto-context):

# Add the Sulcus marketplace
claude plugin marketplace add https://github.com/digitalforgeca/sulcus

# Install the Claude Code plugin
claude plugin install claude-sulcus

This gives you 7 lifecycle hooks (session start context injection, semantic search on every prompt, file change tracking, compaction awareness, task capture, memory file protection, session end tracking) plus 36 MCP tools.

See plugins/claude-code-sulcus/ for full docs.

Alternative: Raw MCP-only (tools without hooks):

claude mcp add sulcus -- sulcus stdio

Connect to OpenClaw

Install the OpenClaw Sulcus plugin:

npm install @digitalforgestudios/openclaw-sulcus

Or via ClawHub skill:

clawhub install digitalforgeca/openclaw-sulcus-skill

SDKs

Language	Package	Install
Python	sulcus	pip install sulcus
Node.js	sulcus	npm install sulcus

Python

from sulcus import Sulcus

client = Sulcus(api_key="your-key", base_url="https://api.sulcus.ca")

# Store a memory
client.remember("User prefers dark mode", memory_type="preference", decay_class="stable")

# Search memories
results = client.recall("user preferences", limit=5)

# Boost a memory
client.boost(node_id="uuid", amount=0.3)

Node.js

import { Sulcus } from 'sulcus';

const client = new Sulcus({ apiKey: 'your-key', baseUrl: 'https://api.sulcus.ca' });

// Store a memory
await client.remember('User prefers dark mode', { memoryType: 'preference', decayClass: 'stable' });

// Search memories
const results = await client.recall('user preferences', { limit: 5 });

// Boost a memory
await client.boost(nodeId, 0.3);

Integrations

Framework	Package	Description
LangChain	sulcus-langchain	Memory backend for LangChain agents
LlamaIndex	sulcus-llamaindex	Vector store + document store
CrewAI	sulcus-crewai	Crew-level shared memory + tools
Deep Agents	sulcus-deepagents	Replaces flat AGENTS.md with persistent memory
Vercel AI	sulcus-vercel-ai	LanguageModelV3Middleware
OpenClaw	@digitalforgestudios/openclaw-sulcus	Memory plugin for OpenClaw
CLI	integrations/cli	Command-line memory management

Memory Types

Type	Description	Decay
episodic	Events, conversations	Fast
semantic	Knowledge, concepts	Slow
preference	User preferences, opinions	Slower
procedural	How-to, processes	Slowest
fact	Stable data, ground truth	Slow

Triggers

Sulcus triggers let memory react to its own lifecycle — no competitor has this.

# Pin any preference that gets recalled
client.create_trigger(
    name="pin-recalled-preferences",
    event="on_recall",
    action="pin",
    filter={"memory_type": "preference"}
)

# Webhook when memories decay below threshold
client.create_trigger(
    name="cold-memory-alert",
    event="on_threshold",
    action="webhook",
    config={"heat_below": 0.1, "url": "https://your-app.com/webhook"}
)

Claude Code Plugin

The plugins/claude-code-sulcus/ directory contains the full Claude Code integration (v2.0.0).