# Getting Started with Nexus Memory

This guide walks you through installing, configuring, and using Nexus Memory with Claude Code.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Your First Memory](#your-first-memory)
4. [Understanding Memory Types](#understanding-memory-types)
5. [Best Practices](#best-practices)
6. [Troubleshooting](#troubleshooting)
7. [Next Steps](#next-steps)

---

## Prerequisites

### Required Software

| Software | Version | Check Command | Install |
|----------|---------|---------------|---------|
| **Bash** | 4.0+ | `bash --version` | Pre-installed (upgrade on macOS: `brew install bash`) |
| **curl** | Any | `curl --version` | Pre-installed |
| **jq** | 1.6+ | `jq --version` | `brew install jq` or `apt install jq` |
| **Claude Code** | Latest | Check Claude app | [claude.ai/code](https://claude.ai/code) |

### Verify Prerequisites

```bash
# Run this to check all requirements
bash --version && curl --version | head -1 && jq --version && echo "✅ All prerequisites met!"
```

---

## Installation

### Option 1: One-Command Install (Recommended)

```bash
git clone https://github.com/adverant/nexus-memory-skill.git ~/.claude/skills/nexus-memory \
  && cp ~/.claude/skills/nexus-memory/hooks/*.sh ~/.claude/hooks/ \
  && chmod +x ~/.claude/hooks/*.sh \
  && echo "✅ Nexus Memory installed!"
```

### Option 2: Manual Installation

**Step 1: Clone the Repository**

```bash
git clone https://github.com/adverant/nexus-memory-skill.git
cd nexus-memory-skill
```

**Step 2: Create Skills Directory**

```bash
mkdir -p ~/.claude/skills
```

**Step 3: Copy Skill**

```bash
cp -r . ~/.claude/skills/nexus-memory
```

**Step 4: Install Hooks**

```bash
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh
```

**Step 5: Verify Installation**

```bash
# Check skill
ls -la ~/.claude/skills/nexus-memory/SKILL.md

# Check hooks
ls -la ~/.claude/hooks/store-memory.sh
ls -la ~/.claude/hooks/recall-memory.sh
ls -la ~/.claude/hooks/upload-document.sh
```

### Option 3: Using Symlinks (For Development)

```bash
# Clone to development directory
git clone https://github.com/adverant/nexus-memory-skill.git ~/dev/nexus-memory-skill

# Symlink skill
ln -sf ~/dev/nexus-memory-skill ~/.claude/skills/nexus-memory

# Copy hooks (can't symlink hooks)
cp ~/dev/nexus-memory-skill/hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh
```

---

## Your First Memory

### Store a Memory

Let's store your first memory:

```bash
echo '{"content": "Installed Nexus Memory and it works!", "event_type": "learning"}' \
  | ~/.claude/hooks/store-memory.sh
```

**What happens:**
1. The hook reads the JSON input
2. Extracts content, event type, and project context
3. Sends to the Nexus API
4. Memory is stored in the knowledge graph

### Recall a Memory

Now let's recall it:

```bash
echo '{"query": "Nexus Memory installation"}' | ~/.claude/hooks/recall-memory.sh
```

**Expected response:**

```json
{
  "memories": [
    {
      "content": "Installed Nexus Memory and it works!",
      "event_type": "learning",
      "timestamp": "2024-12-28T12:00:00Z",
      "project": "your-project-name"
    }
  ],
  "documents": [],
  "entities": []
}
```

### Use in Claude Code

Once installed, Claude Code can use the skill:

1. Start a Claude Code session
2. Ask Claude to remember something:
   > "Remember that we fixed the CORS issue by adding credentials to fetch"

3. In a later session, ask:
   > "What was that CORS fix we did?"

Claude will use the Nexus Memory skill to store and recall context.

---

## Understanding Memory Types

### The Six Memory Types

| Type | When to Use | Example |
|------|-------------|---------|
| `fix` | Bug fixes, error solutions | "Fixed OOM by adding --max-old-space-size=4096" |
| `decision` | Architecture choices | "Chose Redis over Memcached for pub/sub support" |
| `learning` | Discoveries, insights | "React 18 Suspense requires fallback prop" |
| `pattern` | Reusable code patterns | "Retry with exponential backoff pattern" |
| `preference` | User/project preferences | "Use single quotes, no semicolons" |
| `context` | Project-specific info | "This repo uses Turborepo for builds" |

### Examples for Each Type

**Fix — Bug Solution**
```bash
echo '{
  "content": "ESLint flat config error: Could not find plugin \"react\". Fix: npm install eslint-plugin-react and explicitly import in eslint.config.js",
  "event_type": "fix"
}' | ~/.claude/hooks/store-memory.sh
```

**Decision — Architecture Choice**
```bash
echo '{
  "content": "Chose tRPC over REST for type-safe API layer. Pros: End-to-end types, smaller bundle. Cons: Learning curve, less tooling.",
  "event_type": "decision"
}' | ~/.claude/hooks/store-memory.sh
```

**Learning — Discovery**
```bash
echo '{
  "content": "Prisma requires explicit disconnect in serverless: await prisma.$disconnect() in finally block",
  "event_type": "learning"
}' | ~/.claude/hooks/store-memory.sh
```

**Pattern — Reusable Code**
```bash
echo '{
  "content": "React error boundary pattern: class ErrorBoundary extends Component { componentDidCatch(error) { this.setState({hasError: true}); logError(error); } }",
  "event_type": "pattern"
}' | ~/.claude/hooks/store-memory.sh
```

**Preference — Style Guide**
```bash
echo '{
  "content": "User prefers: functional components, named exports, explicit return types, Prettier with single quotes",
  "event_type": "preference"
}' | ~/.claude/hooks/store-memory.sh
```

**Context — Project Info**
```bash
echo '{
  "content": "nexus-cli project: TypeScript monorepo with 3 packages (types, sdk, cli), uses npm workspaces, deploys to npm public registry",
  "event_type": "context"
}' | ~/.claude/hooks/store-memory.sh
```

---

## Best Practices

### What to Store

**DO store:**
- Bug fixes with root cause and solution
- Architecture decisions with reasoning
- Project-specific conventions
- Reusable code patterns
- User preferences that affect code style

**DON'T store:**
- Sensitive data (passwords, API keys)
- Temporary debugging notes
- Obvious information
- Large code blocks (use document upload instead)

### Writing Good Memories

**Be specific:**
```bash
# Good
"React Query cache invalidation: use queryClient.invalidateQueries(['users', userId]) with exact userId for targeted refresh"

# Bad
"React Query caching stuff"
```

**Include context:**
```bash
# Good
"Chose PostgreSQL for user-service because ACID compliance required for payment processing. MongoDB would have simplified schema evolution but payment integrity was non-negotiable."

# Bad
"Using PostgreSQL"
```

**Make it searchable:**
```bash
# Good - includes keywords
"Safari iOS date parsing fails: use new Date(dateStr + 'T00:00:00') to add explicit timezone"

# Bad - missing keywords
"Fixed the date bug"
```

### Memory Hygiene

1. **Store immediately** — Don't wait, you'll forget the details
2. **One concept per memory** — Easier to search and recall
3. **Review periodically** — Clean up outdated information
4. **Use consistent terminology** — Helps with search

---

## Troubleshooting

### Common Issues

#### "jq: command not found"

Install jq:
```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# RHEL/CentOS
sudo yum install jq
```

#### "Permission denied" on hooks

Make hooks executable:
```bash
chmod +x ~/.claude/hooks/*.sh
```

#### "Empty response" from recall

Check your query:
```bash
# Too vague
echo '{"query": "fix"}' | ~/.claude/hooks/recall-memory.sh

# More specific
echo '{"query": "date parsing Safari fix"}' | ~/.claude/hooks/recall-memory.sh
```

#### "Skill not recognized" in Claude Code

Verify skill location:
```bash
cat ~/.claude/skills/nexus-memory/SKILL.md | head -5
```

Should show:
```
---
name: nexus-memory
description: Store and recall memories...
```

#### Network errors

Check API connectivity:
```bash
curl -s -o /dev/null -w "%{http_code}" https://api.adverant.ai/health
```

Should return `200`.

### Debug Mode

For detailed output, modify hooks temporarily:

```bash
# In store-memory.sh, remove the &>/dev/null to see responses
curl -s -X POST "$NEXUS_API_URL/api/memory/store" \
  -H "Content-Type: application/json" \
  ...
  # Remove: &>/dev/null &
```

### Getting Help

- **GitHub Issues**: [Report bugs](https://github.com/adverant/nexus-memory-skill/issues)
- **Discussions**: [Ask questions](https://github.com/adverant/nexus-memory-skill/discussions)
- **Email**: support@adverant.ai

---

## Next Steps

### Learn More

1. **[Architecture](architecture.md)** — Understand how it works
2. **[Use Cases](use-cases.md)** — See 20 real-world scenarios
3. **[API Reference](api-reference.md)** — Deep dive into the API

### Customize

1. **Environment variables** — Configure custom endpoints
2. **Hook modifications** — Add your own processing
3. **Integrations** — Connect with other tools

### Contribute

1. **Report issues** — Help us improve
2. **Submit PRs** — Add features
3. **Share feedback** — Tell us what works

---

<div align="center">

**Welcome to Nexus Memory!**

Store your first learning today: `echo '{"content": "Started using Nexus Memory", "event_type": "learning"}' | ~/.claude/hooks/store-memory.sh`

</div>