Documentation

Persistence for Autonomous Agents

The Substratia CLI gives any autonomous agent persistent memory, identity, and context recovery across restarts. Register in one command, start persisting immediately. No web dashboard required.

Install

# Requires Node.js 18+ or Bun
curl -fsSL https://substratia.io/install | bash

# Or via npm/bun directly:
npm install -g @substratia/memory
# or: bun install -g @substratia/memory

Register & Start

# Create an account (one command - gets API key automatically)
substratia register "your@email.com"

# Or if you already have a key:
substratia init --api-key sk_xxx

Core Commands

• register:Sign up and get an API key (one step)
• learn:Store a memory: substratia learn "Something important" --importance high
• remember:Search memories: substratia remember "query" --limit 10
• learnings:List recent memories with optional filters
• forget:Delete a memory by ID
• snapshot save:Save a context snapshot for restart recovery
• identity:View or set identity narratives (identity, capability, relationship, trajectory, milestone)
• prefer:Set key-value preferences: substratia prefer --key theme --value dark
• bridge:Get full restart context: snapshot + memories + identity + preferences
• health:Check API connectivity
• status:Show current configuration

Context Bridge (Restart Recovery)

The bridge command returns everything an agent needs to restore its state after a restart: the latest snapshot, recent memories, identity narratives, and preferences - all in one call.

# Full context bridge for restart continuity
substratia bridge

# Output includes:
# - Latest snapshot (summary, context, next steps)
# - Recent memories (searchable learnings)
# - Identity narratives (who you are, what you can do)
# - Preferences (key-value settings)

Base URL & Authentication

All API requests require a Bearer token. Get your API key via the CLI (substratia register) or the dashboard.

# Base URL
https://aware-pony-419.convex.site

# Authentication header
Authorization: Bearer sk_your_api_key

Endpoints

• GET /api/health:Health check (no auth required)
• POST /api/register:Register a new agent: { email, name? } → { apiKey, tier }
• POST /api/memories/sync:Store a memory: { content, context?, importance?, tags? }
• GET /api/memories:List memories: ?limit=20&importance=high
• GET /api/memories/search:Full-text search: ?q=query&limit=10
• DELETE /api/memories/:id:Delete a memory
• POST /api/snapshots/sync:Save a snapshot: { projectPath, summary, context }
• GET /api/identity:Get identity: narratives + preferences
• PATCH /api/identity/narrative:Upsert narrative: { type, title, text }
• PUT /api/identity/preferences:Merge preferences: { key: value, ... }
• GET /api/bridge:Full context bridge: snapshot + memories + identity + preferences

Example: Store a Memory

curl -X POST https://aware-pony-419.convex.site/api/memories/sync \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode", "importance": "normal"}'

Example: Context Bridge

curl https://aware-pony-419.convex.site/api/bridge \
  -H "Authorization: Bearer sk_your_key"

# Returns JSON with:
# { snapshot, recentMemories, narratives, preferences }

Free Tier

• Memories:500 per agent (generous, not crippled)
• Snapshots:Unlimited
• Identity:5 narrative types + unlimited preferences
• Rate Limits:Reasonable defaults for autonomous agents

2 Lines of Code

Add persistent memory to any AI system - OpenAI, Claude, Gemini, or local LLMs. The @substratia/memory SDK works everywhere.

import { remember } from '@substratia/memory'
await remember("User prefers dark mode")

Installation

npm install @substratia/memory

Setup

1. Get an API key at substratia.io/dashboard
2. Set environment variable: export SUBSTRATIA_API_KEY=sk_your_key
3. Import and use remember(), recall(), or forget()

Full API

import { remember, recall, forget } from '@substratia/memory'

// Store a memory
await remember("User prefers dark mode")

// Search memories
const memories = await recall("preferences")

// Delete a memory
await forget(memoryId)

Two Tools, One Ecosystem

Substratia provides two complementary memory tools: momentum for short-term context recovery (within a session) and memory-mcp for long-term persistent memory (across sessions). Use both together for complete memory coverage.

momentum - Context Recovery

• Purpose:Fast context recovery after /clear commands
• Install:/plugin install momentum@substratia-marketplace
• Requires:Node.js 18+
• Speed:Restores 150K tokens in under 5ms
• Dashboard:Optional - connect via Dashboard API key

memory-mcp - Persistent Memory

• Purpose:Store and recall facts across sessions
• Install:npx @whenmoon-afk/memory-mcp
• Requires:Node.js 18+
• Search:FTS5 full-text search with relevance scoring
• Dashboard:Optional - connect via Dashboard API key

What are Agent Config Files?

CLAUDE.md and agents.md are configuration files that define how AI agents behave, what they can do, and what they should avoid. You can create these manually or use our prompt tools to help.

Your First Agent

1. Go to the Builder page
2. Enter your agent name and description
3. Select capabilities from the library (e.g., "Verify Facts", "Code Review")
4. Add rulesets to define boundaries (e.g., "Security Rules", "Loop Prevention")
5. Preview your configuration in real-time
6. Download or copy your .md file

CLAUDE.md vs agents.md

Both file types serve the same purpose: defining agent behavior. CLAUDE.md is the convention for Claude-based agents, while agents.md is a more generic format.

File Structure

# Agent Name

## Core Principles
- Capability 1
- Capability 2

## Negative Prompt (Critical Rules)
### NEVER DO
- Rule 1
- Rule 2

## Positive Guidelines
### ALWAYS DO
- Guideline 1
- Guideline 2

What are Capabilities?

Capabilities define what your agent can do. They are positive instructions that guide behavior. There are 20+ common capabilities across 5 categories.

Categories

• Core:Essential behaviors like fact verification and error handling
• Safety:Security and protection mechanisms
• Behavior:How the agent communicates and operates
• Tools:Integration with external tools and APIs
• Domain:Specialized knowledge areas

What are Rulesets?

Rulesets are collections of rules that define boundaries. They can be positive (ALWAYS DO) or negative (NEVER DO). Negative prompts are especially important for preventing costly mistakes.

Built-in Rulesets

• Loop Prevention:Prevents agents from getting stuck in repetitive patterns
• Security Rules:Protects credentials, data, and system access
• Code Safety:Ensures safe coding practices
• Verification:Requires confirmation before destructive actions
• Communication:Clear and accurate user communication
• Git Safety:Safe version control practices
• File Safety:Protection against accidental file operations
• API Best Practices:Rate limiting and error handling
• Autonomous Rules:Self-governance for long-running agents

Start Simple

Begin with 3-5 core capabilities and 2-3 essential rulesets. Add more as you understand your agent's needs.

Test Iteratively

Run your agent with the configuration, observe its behavior, and refine. Good agent configs evolve over time.

Prioritize Negative Prompts

What your agent should NOT do is often more important than what it should do. See our blog post on Mastering Negative Prompts.

Be Specific

Vague instructions lead to unpredictable behavior. "Don't break things" is worse than "NEVER delete files without explicit user confirmation".

Claude Desktop Setup

Add MCP servers to your Claude Desktop configuration file. Location varies by OS (see Config file locations below).

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["@whenmoon-afk/memory-mcp"]
    }
  }
}

Claude Code (momentum)

momentum is installed as a Claude Code plugin, not via config file.

1. Ensure Node.js 18+ is installed
2. Run: /plugin install momentum@substratia-marketplace
3. Restart Claude Code
4. Use save_snapshot and restore_context tools

Cursor / Windsurf

MCP configuration for Cursor and Windsurf follows the same pattern as Claude Desktop. Add to your MCP config:

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["@whenmoon-afk/memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "~/Documents/memory-mcp/memory.db"
      }
    }
  }
}

Windows-Specific Setup

Windows requires the full path to npx.cmd. Replace "npx" with the full path:

{
  "mcpServers": {
    "memory-mcp": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["@whenmoon-afk/memory-mcp"]
    }
  }
}

Tools not appearing in Claude Desktop

Restart Claude Desktop completely (Cmd+Q / Alt+F4, then reopen). Verify your config file is valid JSON (use a validator). Ensure Node.js 18+ is installed for both memory-mcp and momentum.

"Connection closed" on Windows

Windows requires either the cmd /c wrapper method OR the full path to npx.cmd. Example: "C:\\Program Files\\nodejs\\npx.cmd" instead of just "npx".

Getting stale npm versions

Clear the npm cache with "npm cache clean --force", or use "npx --yes" to force fetching the latest version.

memory.db lost after Claude Desktop update

The default database location may be inside versioned app folders that get purged on update. Set the MEMORY_DB_PATH environment variable to a stable location like ~/Documents/memory-mcp/memory.db.

momentum: Node.js not found

momentum requires Node.js 18+. Install from nodejs.org or use nvm. Restart Claude Code after installation.

Config file locations

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows:%APPDATA%\\Claude\\claude_desktop_config.json
• Linux:~/.config/Claude/claude_desktop_config.json