Documentation

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:Bun runtime v1.0.0+
• Speed:Restores 150K tokens in under 5ms

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

What is AgentForge?

AgentForge is a visual builder for creating AI agent configuration files (CLAUDE.md and agents.md). These files define how AI agents behave, what they can do, and what they should avoid.

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. AgentForge supports both.

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. AgentForge includes 20+ built-in 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".

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 memory-mcp, or Bun 1.0+ for 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: Bun not found

Install Bun with: curl -fsSL https://bun.sh/install | bash (macOS/Linux) or use the Windows installer from bun.sh. Restart your terminal 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