Windsurf setup

pip install atlas-mem

#!/usr/bin/env python3
"""
Atlas memory bridge for Windsurf Cascade.

Commands:
  python .windsurf/atlas.py store  "fact to remember"
  python .windsurf/atlas.py recall "what do you need to know?"
  python .windsurf/atlas.py ask    "complex relational question"
  python .windsurf/atlas.py health
"""

import sys
import os
import json
from atlas_mem import AtlasMem

# Project-scoped memory — persona isolates this project from others
brain = AtlasMem(
    api_key=os.environ["ATLAS_API_KEY"],
    base_url="https://api.bsyncs.com",
    user_id=os.environ.get("ATLAS_USER_ID", "windsurf-user"),
    persona=os.environ.get("ATLAS_PROJECT", os.path.basename(os.getcwd())),
)

def store(fact: str):
    r = brain.add(fact, source="user")
    print(f"[Atlas] Stored: {r.entities_extracted} entities, {r.triples_extracted} relations, {r.episodic_chunks} chunks")

def recall(query: str):
    r = brain.search(query, k=6)
    if not r.facts:
        print("[Atlas] No relevant memories found.")
        return
    print("[Atlas Memory]\n" + r.format(max_facts=6))

def ask(question: str):
    answer = brain.ask(question, max_hops=3)
    print(f"[Atlas Graph QA]\n{answer}")

def health():
    h = brain.health()
    status = "✓ online" if h.get("ready") else "✗ offline"
    print(f"[Atlas] {status} — Neo4j: {h['neo4j']}, Qdrant: {h['qdrant']}, Redis: {h['redis']}")

commands = {"store": store, "recall": recall, "ask": ask, "health": health}

if __name__ == "__main__":
    if len(sys.argv) < 2 or sys.argv[1] not in commands:
        print(f"Usage: atlas.py [{' | '.join(commands)}] <text>")
        sys.exit(1)

    cmd = sys.argv[1]
    text = " ".join(sys.argv[2:]) if len(sys.argv) > 2 else ""
    commands[cmd](text)

# Cascade Agent Rules

## Memory System (Atlas)

You have a persistent memory tool available at:
  `python .windsurf/atlas.py <command> <text>`

### Rules for using Atlas

1. **Before any architectural question**, run:
   `python .windsurf/atlas.py recall "<topic>"`
   and include the result in your context before answering.

2. **Before suggesting a library, pattern, or tool**, check Atlas first to see if a decision was already made.

3. **After any significant decision or discovery**, store it:
   `python .windsurf/atlas.py store "<clear, self-contained fact>"`

### Examples of facts worth storing

- "The auth service uses RS256 JWT, not HS256. The public key is at /keys/auth.pub"
- "Do not use axios — the team standardised on fetch with a custom wrapper in lib/api.ts"
- "The background job queue uses BullMQ with Redis. Jobs live in /workers/"
- "Database migrations run via Alembic. Never edit migration files after they have been committed."

### Examples of facts NOT worth storing

- Trivial implementation details easily found in code
- Temporary debug notes
- Facts that are obvious from the codebase structure

ATLAS_API_KEY=atlas_your_key_here
ATLAS_USER_ID=your-name
ATLAS_PROJECT=my-project-name    # used as the persona — separates per-project memory

export $(cat .env | xargs)

# Check health
python .windsurf/atlas.py health
# [Atlas] ✓ online — Neo4j: connected, Qdrant: connected, Redis: connected

# Store your first convention
python .windsurf/atlas.py store "This project uses pnpm workspaces. All packages are in the /packages directory."

# Retrieve it
python .windsurf/atlas.py recall "project structure monorepo"

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Atlas: Recall",
      "type": "shell",
      "command": "python .windsurf/atlas.py recall \"${input:recallQuery}\"",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "shared"
      }
    },
    {
      "label": "Atlas: Store",
      "type": "shell",
      "command": "python .windsurf/atlas.py store \"${input:storeFact}\"",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "recallQuery",
      "description": "What do you want to recall from Atlas?",
      "type": "promptString"
    },
    {
      "id": "storeFact",
      "description": "What fact do you want to store in Atlas?",
      "type": "promptString"
    }
  ]
}