Fix: openmemory setup script and readme instructions

[lopeselio]

Description

Fixes #79 - The openmemory-setup.sh script was failing with "Script not found 'build'" error after fresh clone because the OpenMemory backend wasn't included in the repository.

This PR improves the setup script to:

• Automatically clone the OpenMemory backend from CaviraOSS/OpenMemory if missing
• Remove the .git directory from the cloned repo to avoid nested git repositories
• Add comprehensive validation checks (backend directory, package.json, build script)
• Create .env file with placeholder values (no secrets exposed)
• Install dependencies automatically if needed
• Provide clear error messages and next steps

Also updated the README with complete OpenMemory setup instructions and configuration guide.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Release (version bump)

Release

Is this a release? No - this is a bug fix and documentation update.

Testing

Test Environment Setup

Prerequisites:

• Fresh clone of the repository (or remove services/openmemory/ directory to simulate)
• Bun installed (bun --version)
• Git installed
• Internet connection (for cloning OpenMemory backend)

Repository Structure:

mallory/
├── services/
│   ├── openmemory-setup.sh  # Setup script (included in repo)
│   └── openmemory/          # Backend directory (gitignored, created by script)
│       └── backend/         # Cloned from CaviraOSS/OpenMemory
│           ├── package.json
│           ├── src/
│           ├── dist/        # Created after build
│           └── .env         # Created by script
├── apps/
│   ├── client/
│   └── server/
└── .gitignore              # Contains: services/openmemory/

Test Scenarios

1. Fresh Clone Scenario (Backend Missing)

Setup:

# From repository root: /Users/lopeselio/Desktop/Development/solana/solana-com/dark-research/mallory
# Simulate fresh clone by removing backend (if it exists)
rm -rf services/openmemory/backend

# Make script executable
chmod +x services/openmemory-setup.sh

Run Test:

# Run the setup script from repository root
./services/openmemory-setup.sh

Expected Behavior:

• ✅ Script detects missing backend
• ✅ Automatically clones from CaviraOSS/OpenMemory to services/openmemory/backend
• ✅ Removes .git directory from cloned repo
• ✅ Creates .env file at services/openmemory/backend/.env with placeholder values
• ✅ Installs dependencies with bun install in services/openmemory/backend
• ✅ Builds TypeScript backend with bun run build
• ✅ Creates services/openmemory/backend/dist/ directory
• ✅ Shows success message with next steps

Verification Commands:

# Check backend was cloned
ls -la services/openmemory/backend/

# Verify .git was removed (should not exist)
test -d services/openmemory/backend/.git && echo "❌ .git still exists" || echo "✅ .git removed"

# Check .env was created with placeholders
grep -q "your-gemini-api-key-here" services/openmemory/backend/.env && echo "✅ .env has placeholders" || echo "❌ .env missing placeholders"
grep -q "your-secure-api-key-here" services/openmemory/backend/.env && echo "✅ API key placeholder found" || echo "❌ API key placeholder missing"

# Verify build output exists
test -d services/openmemory/backend/dist && echo "✅ Build successful - dist/ exists" || echo "❌ Build failed - dist/ missing"
test -f services/openmemory/backend/dist/server/index.js && echo "✅ Server build output exists" || echo "❌ Server build output missing"

# Verify dependencies installed
test -d services/openmemory/backend/node_modules && echo "✅ Dependencies installed" || echo "❌ Dependencies missing"

2. Backend Already Exists (Idempotent Test)

Setup:

# Ensure backend exists (from previous test or existing setup)
# Run script again
./services/openmemory-setup.sh

Expected Behavior:

• ✅ Skips cloning (backend exists at services/openmemory/backend)
• ✅ Skips .env creation (already exists at services/openmemory/backend/.env)
• ✅ Skips dependency installation (node_modules exists)
• ✅ Only runs build step
• ✅ Shows success message

Verification:

# Verify script didn't recreate existing files unnecessarily
# Check .env wasn't overwritten (if you had custom values)
cat services/openmemory/backend/.env

3. Validation Checks

Test A: Missing package.json

# Create backend directory without package.json
rm -rf services/openmemory/backend
mkdir -p services/openmemory/backend
./services/openmemory-setup.sh

Expected: Script exits with error: "❌ OpenMemory backend package.json not found!"

Test B: Missing build script

# Create backend with package.json but no build script
rm -rf services/openmemory/backend
mkdir -p services/openmemory/backend
echo '{"name": "test", "scripts": {}}' > services/openmemory/backend/package.json
./services/openmemory-setup.sh

Expected: Script exits with error: "❌ 'build' script not found in package.json!"

4. Error Handling

Test Clone Failure:

# Simulate network issue (optional - requires manual intervention)
# Temporarily disable network or use invalid URL
# Script should exit with: "❌ Failed to clone OpenMemory backend!"

Test Build Failure:

# If build fails, script should exit with error code and helpful message
# Expected: "❌ Build failed!" with troubleshooting steps

5. Configuration Verification

After Successful Setup:

# Check .env file structure
cat services/openmemory/backend/.env

# Verify no secrets are exposed (should see placeholders only)
grep -E "(your-.*-here|placeholder)" services/openmemory/backend/.env

# Verify all required variables are present
grep -q "OM_EMBED_PROVIDER" services/openmemory/backend/.env && echo "✅ OM_EMBED_PROVIDER found"
grep -q "OM_GEMINI_API_KEY" services/openmemory/backend/.env && echo "✅ OM_GEMINI_API_KEY found"
grep -q "OM_API_KEY" services/openmemory/backend/.env && echo "✅ OM_API_KEY found"
grep -q "OM_PORT" services/openmemory/backend/.env && echo "✅ OM_PORT found"
grep -q "OM_DB_TYPE" services/openmemory/backend/.env && echo "✅ OM_DB_TYPE found"

Expected: All variables present with placeholder values, no actual API keys exposed.

6. Integration with Server

Test Server Connection:

# 1. Configure OpenMemory .env with actual API keys
cd services/openmemory/backend
# Edit .env: Replace placeholders with actual values
#   OM_GEMINI_API_KEY=your-actual-key
#   OM_API_KEY=your-secure-key

# 2. Start OpenMemory backend
bun start
# Should start on http://localhost:8080

# 3. In another terminal, configure server .env
# Edit apps/server/.env and add:
#   OPENMEMORY_URL=http://localhost:8080
#   OPENMEMORY_API_KEY=your-secure-key  # Must match OM_API_KEY above

# 4. Start server and verify connection
cd apps/server
bun run dev
# Check logs for successful OpenMemory connection

Automated Testing Performed

• ✅ Validated script syntax with bash -n services/openmemory-setup.sh
• ✅ Tested all conditional checks and validation logic
• ✅ Verified path navigation works correctly (cd into services/openmemory/backend and back to root)
• ✅ Confirmed .env template has no exposed secrets (uses placeholders)
• ✅ Tested error handling and exit codes
• ✅ Verified script is idempotent (can run multiple times safely)
• ✅ Confirmed .git directory removal from cloned repository

Manual Testing Checklist

• Fresh clone: Script automatically clones backend to services/openmemory/backend
• Fresh clone: .git directory is removed from cloned repo
• Fresh clone: .env file created at services/openmemory/backend/.env with placeholders
• Fresh clone: Dependencies installed successfully in services/openmemory/backend/node_modules
• Fresh clone: Build completes and creates services/openmemory/backend/dist/
• Existing setup: Script skips unnecessary steps (idempotent)
• Error handling: Missing backend shows helpful error message
• Error handling: Missing package.json shows helpful error message
• Error handling: Missing build script shows helpful error message
• Configuration: No secrets exposed in .env template
• Documentation: README instructions are clear and complete

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing tests pass locally with my changes
• If releasing, I have verified the version number is correct and follows semantic versioning

[vercel]

@lopeselio is attempting to deploy a commit to the dark Team on Vercel.

A member of the Team first needs to authorize it.

[lopeselio]

hey Edgar @edgarpavlovsky , please check this out for issue #79

[edgarpavlovsky]

this one is already being worked on in #98 so closing