Claude Code Setup

pip install atlas-mem

#!/usr/bin/env python3
"""
Atlas memory tool for Claude Code.
Called by Claude Code via slash commands or CLAUDE.md instructions.
"""

import sys
import os
import json
from atlas_mem import AtlasMem

brain = AtlasMem(
    api_key=os.environ["ATLAS_API_KEY"],
    base_url="https://api.bsyncs.com",
    user_id=os.environ.get("ATLAS_USER_ID", "claude-code-user"),
    persona=os.environ.get("ATLAS_PERSONA", "shared"),
)

def cmd_store(text: str) -> None:
    result = brain.add(text, source="user")
    print(json.dumps({
        "status": "stored",
        "entities": result.entities_extracted,
        "relations": result.triples_extracted,
        "chunks": result.episodic_chunks,
    }))

def cmd_recall(query: str, k: int = 5) -> None:
    results = brain.search(query, k=k)
    output = {
        "context": results.context,
        "facts": [
            {
                "fact": f["fact"],
                "score": round(f["score"], 3),
                "source": f.get("source_type"),
            }
            for f in results.facts
        ],
    }
    print(json.dumps(output, indent=2))

def cmd_ask(question: str) -> None:
    answer = brain.ask(question, max_hops=3)
    print(json.dumps({"answer": answer}))

def cmd_stats() -> None:
    print(json.dumps(brain.stats()))

commands = {
    "store": cmd_store,
    "recall": cmd_recall,
    "ask": cmd_ask,
    "stats": cmd_stats,
}

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print(json.dumps({"error": "Usage: atlas_tool.py <store|recall|ask|stats> <text>"}))
        sys.exit(1)

    command = sys.argv[1]
    text = " ".join(sys.argv[2:])

    if command not in commands:
        print(json.dumps({"error": f"Unknown command: {command}"}))
        sys.exit(1)

    commands[command](text)

chmod +x ~/.claude/atlas_tool.py

# Add to ~/.zshrc or ~/.bashrc
export ATLAS_API_KEY="atlas_your_key_here"
export ATLAS_USER_ID="your-name"
export ATLAS_PERSONA="claude-code"

# Project Memory — Claude Code Instructions

## Atlas Memory System

You have access to a persistent memory tool via Python:
`python ~/.claude/atlas_tool.py <command> <text>`

### Commands
- `store "<fact>"` — Save an important fact, decision, or discovery
- `recall "<query>"` — Retrieve relevant memories before answering
- `ask "<question>"` — Answer a complex question using graph reasoning
- `stats` — Check memory system status

### When to use memory

**ALWAYS recall before:**
- Answering questions about the codebase architecture
- Suggesting library or tool choices
- Writing code that touches existing patterns/conventions

**ALWAYS store after:**
- A successful architectural decision is made
- A non-obvious bug is found and fixed
- A new coding convention is established
- An important dependency constraint is discovered

### Example usage
```bash
python ~/.claude/atlas_tool.py store "The payment service uses idempotency keys to prevent double charges. Always pass X-Idempotency-Key header."
python ~/.claude/atlas_tool.py recall "payment idempotency"
python ~/.claude/atlas_tool.py ask "How does the payment retry logic work?"

---

## Step 5 — Test the integration

Open Claude Code in your project directory:

```bash
claude

> Store the fact that this project uses pnpm, not npm, and all scripts must use "pnpm run" not "npm run"

> Before suggesting any package management commands, recall project tooling preferences

## End of session

Before finishing, always:
1. `python ~/.claude/atlas_tool.py store "<summary of what was built/changed/decided today>"`
2. `python ~/.claude/atlas_tool.py store "<any new conventions or constraints discovered>"`