Skip to main content
Long-term memory for Zo powered by Nebula. Stores conversations, decisions, preferences, and project context so Zo can recall them across sessions. Stored content feeds into a vector graph that returns entities, facts, and source utterances.
You’ll need a Nebula API key and collection ID before starting. Get both at trynebula.ai

​
Installation

​
One-Command Setup

Replace YOUR_API_KEY and YOUR_COLLECTION_ID, then paste into your Zo terminal: 
bash -c '
set -euo pipefail

if ! command -v node &>/dev/null && ! command -v npx &>/dev/null; then
  echo "Error: Node.js is required. Install from https://nodejs.org"
  exit 1
fi
if ! command -v jq &>/dev/null; then
  echo "Error: jq is required. Install: sudo apt-get install jq"
  exit 1
fi

NEBULA_API_KEY="YOUR_API_KEY"
NEBULA_COLLECTION_ID="YOUR_COLLECTION_ID"
CONFIG_DIR="$HOME/.config/nebula"
ENV_FILE="$CONFIG_DIR/zo.env"
MCPORTER_CONFIG="$HOME/.mcporter/mcporter.json"
MCPORTER_VERSION="0.7.3"
SKILLS_DIR="/home/workspace/Skills/nebula-memory"
GH="https://raw.githubusercontent.com/nebula-agi/zo-nebula-memory/main"

# Install skill
echo "Installing nebula-memory skill..."
mkdir -p "$SKILLS_DIR/scripts"
curl -fsSL "$GH/SKILL.md" -o "$SKILLS_DIR/SKILL.md"
curl -fsSL "$GH/scripts/memory.sh" -o "$SKILLS_DIR/scripts/memory.sh"
chmod +x "$SKILLS_DIR/scripts/memory.sh"

# Write credentials
mkdir -p "$CONFIG_DIR"
printf "export NEBULA_API_KEY=%s\nexport NEBULA_COLLECTION_ID=%s\n" \
  "$NEBULA_API_KEY" "$NEBULA_COLLECTION_ID" > "$ENV_FILE"
chmod 600 "$ENV_FILE"

# Configure MCPorter
SERVER_JSON=$(jq -n --arg url "https://mcp.trynebula.ai/mcp/" '"'"'{
  "nebula-memory": {
    "baseUrl": $url,
    "headers": {
      "Authorization": "Bearer ${NEBULA_API_KEY}",
      "X-Collection-ID": "${NEBULA_COLLECTION_ID}"
    }
  }
}'"'"')

mkdir -p "$(dirname "$MCPORTER_CONFIG")"
if [ -f "$MCPORTER_CONFIG" ]; then
  if ! jq empty "$MCPORTER_CONFIG" 2>/dev/null; then
    echo "Error: $MCPORTER_CONFIG contains invalid JSON. Fix it and re-run."
    exit 1
  fi
  EXISTING=$(cat "$MCPORTER_CONFIG")
  if [ -z "$EXISTING" ] || [ "$EXISTING" = "{}" ]; then
    echo "{\"mcpServers\": $SERVER_JSON}" | jq "." > "$MCPORTER_CONFIG"
  else
    echo "$EXISTING" | jq --argjson server "$SERVER_JSON" \
      ".mcpServers = ((.mcpServers // {}) * \$server)" > "$MCPORTER_CONFIG"
  fi
else
  echo "{\"mcpServers\": $SERVER_JSON}" | jq "." > "$MCPORTER_CONFIG"
fi

# Verify
echo "Running test search..."
export NEBULA_API_KEY
export NEBULA_COLLECTION_ID
if npx -y "mcporter@$MCPORTER_VERSION" --config "$MCPORTER_CONFIG" \
  call "nebula-memory.search_memories" query:"setup test" 2>&1; then
  echo ""
  echo "Setup complete! Nebula memory is ready."
else
  echo ""
  echo "Warning: Test search failed. Check your API key and collection ID."
  exit 1
fi
'
The command installs the nebula-memory skill, writes credentials to ~/.config/nebula/zo.env, configures MCPorter as the MCP bridge, and runs a test search.

​
Activating Memory

After installation, Zo defaults to its built-in rules system and will not use Nebula Memory automatically. You need to tell it to use the skill.

​
Usage

​
What gets stored

  • Preferences and conventions (“always use TypeScript”)
  • Decisions and their reasoning (“chose Next.js App Router for RSC support”)
  • Corrections and clarifications
  • Project setup details and architecture notes

​
Skill CLI

Run search and store directly from the Zo terminal: 
# Search - use short keyword phrases, not full sentences
bash /home/workspace/Skills/nebula-memory/scripts/memory.sh search "auth library preference"

# Store - be specific and self-contained
bash /home/workspace/Skills/nebula-memory/scripts/memory.sh add "acme app | user | routing: decided on Next.js App Router for RSC support"
The skill uses the same search_memories and add_memory MCP tools described in the MCP integration guide.

​
File Locations

FilePathPurpose
Credentials~/.config/nebula/zo.envAPI key and collection ID
MCPorter config~/.mcporter/mcporter.jsonMCP server definition with auth headers
Skill instructions/home/workspace/Skills/nebula-memory/SKILL.mdTeaches Zo’s AI when and how to use memory
Skill CLI/home/workspace/Skills/nebula-memory/scripts/memory.shBash wrapper for search and store

​
Requirements

  • Zo account
  • Node.js (for MCPorter)
  • jq

​
Troubleshooting

​
Command not found: node

MCPorter requires Node.js: 
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

​
Connection test fails

Verify credentials are set: 
source ~/.config/nebula/zo.env
echo $NEBULA_API_KEY
If the key prints but you get a 401, generate a new one from trynebula.ai.

​
No search results

Content becomes searchable after Nebula finishes extraction, typically a few seconds after storing.

​
Updating the skill

Pull the latest files from the source repository: 
curl -fsSL https://raw.githubusercontent.com/nebula-agi/zo-nebula-memory/main/SKILL.md \
  -o /home/workspace/Skills/nebula-memory/SKILL.md
curl -fsSL https://raw.githubusercontent.com/nebula-agi/zo-nebula-memory/main/scripts/memory.sh \
  -o /home/workspace/Skills/nebula-memory/scripts/memory.sh