Give your agents a mind that pages memory in and out of context based on thermodynamic importance.

AI agents forget. Context windows fill up, old facts disappear, and naive RAG pulls irrelevant noise. Sulcus fixes this with a Virtual Memory Management Unit (vMMU) — treating the prompt window as registers and local storage as RAM.

• Thermodynamic Decay — Every memory has heat. New facts start hot (1.0); unused facts cool over time. Each memory type decays at its own rate.
• Topological Diffusion — Heat diffuses through the knowledge graph via recursive CTEs. Mentioning a topic warms up related concepts automatically.
• Automatic Page-In/Out — Builds a <sulcus_context> block each prompt, paging in hot memories and paging out cold ones to stay within token budgets.
• Memory Consolidation — Folds cold episodic memories into dense semantic summaries. Meaning preserved, tokens saved.
• Memory Triggers — Programmable reactive rules on the knowledge graph. When a memory event happens (stored, recalled, decays, crosses a threshold), fire an action automatically.
• Pinning — Mark memories as permanent. Pinned memories are immune to decay — the agent or user decides what persists.

Built in Rust with embedded PostgreSQL 17 (via pg-embed).

• Sub-50ms latency for context building and injection
• 384-dim embeddings via ONNX Runtime (all-MiniLM-L6-v2)
• Local-first — your data never leaves your machine

Build from source:

git clone https://github.com/digitalforgeca/sulcus
cd sulcus
cargo build -p sulcus-local --release

Run the MCP server:

./target/release/sulcus-local stdio

Configure Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "sulcus": {
      "command": "/absolute/path/to/sulcus-local",
      "args": ["stdio"]
    }
  }
}

Or run with the local control panel:

./target/release/sulcus-local serve --port 4203
# Dashboard at http://localhost:4203

pip install sulcus          # Python (zero dependencies)
npm install sulcus          # Node.js (zero dependencies)

from sulcus import Sulcus

client = Sulcus(api_key="sk-...")
client.remember("User prefers dark mode", memory_type="preference")
results = client.search("UI preferences")

import { Sulcus } from "sulcus";

const client = new Sulcus({ apiKey: "sk-..." });
await client.remember("User prefers dark mode", { memoryType: "preference" });
const results = await client.search("UI preferences");

Reactive rules on the knowledge graph — no other memory system has this.

6 events: on_store, on_recall, on_decay, on_boost, on_relate, on_threshold

7 actions: notify, boost, pin, tag, deprecate, webhook, chain

Filters: memory_type, namespace, label_pattern (case-insensitive), heat_above/below

# Pin anything the agent searches for
client.create_trigger("on_recall", "pin", name="Auto-pin recalled")

# Webhook Slack when deployment procedures are stored
client.create_trigger("on_store", "webhook",
    action_config={"url": "https://hooks.slack.com/..."},
    filter_label_pattern="deploy")

# Auto-deprecate cold memories
client.create_trigger("on_threshold", "deprecate",
    filter_heat_below=0.05)

5 MCP tools: create_trigger, list_triggers, update_trigger, delete_trigger, trigger_history

Sulcus speaks MCP (Model Context Protocol) natively:

LLM Prompt (Registers)
    |
    v
sulcus-local (MCP Sidecar)
    |
    +-- Embedded PostgreSQL 17 (RAM)
    +-- ONNX Runtime (Embeddings)
    +-- Thermodynamic Engine (Decay / Diffusion / Consolidation)
    +-- Trigger Engine (Reactive Rules)
    +-- WASM Sync Client (optional cloud sync)

30+ MCP tools available: record_memory, search_memory, build_context, list_hot_nodes, page_in, create_trigger, configure_thermodynamics, and more.

crates/
  sulcus-core/       # Thermodynamic engine, types, decay profiles
  sulcus-local/      # MCP sidecar, embedded PG, trigger engine, local panel
  sulcus-wasm/       # WASM sync client for browsers
sdks/
  python/            # Python SDK (stdlib only, async via httpx)
  node/              # Node.js SDK (native fetch, TypeScript)

MIT. Free to use, modify, and distribute.

See LICENSE-MIT for details.

Contributions welcome. Areas of interest:

• Thermodynamic decay algorithms and tuning
• New storage backends
• Agent framework adapters
• Trigger action implementations
• Benchmark tasks for MemBench

Built in Rust for the agentic future.