When to Use What: Feature Decision Guide¶

The Big Picture¶

Nexus offers many features - memory, permissions, workflows, mounts, search, skills, and more. Which ones should you use? This guide helps you choose the right Nexus features for your use case, avoiding over-engineering while ensuring you don't miss critical capabilities.

Think of this as a flowchart for Nexus architecture decisions.

Quick Decision Tree¶

graph TD
    Start[I need to...] --> Q1{Store data?}

    Q1 -->|Yes| Q2{Multiple backends<br/>local, S3, DB?}
    Q2 -->|Yes| Mounts[Use Mounts & Backends]
    Q2 -->|No| Simple[Use Basic VFS<br/>read, write, mkdir]

    Q1 -->|No| Q3{Agent memory<br/>across sessions?}
    Q3 -->|Yes| Memory[Use Memory API]
    Q3 -->|No| Q4{Multi-agent<br/>collaboration?}

    Q4 -->|Yes| Q5{Simple teams<br/>or complex orgs?}
    Q5 -->|Simple| AgentPerms[Use Agent Permissions]
    Q5 -->|Complex| ReBAC[Use ReBAC]

    Q4 -->|No| Q6{Event-driven<br/>automation?}
    Q6 -->|Yes| Workflows[Use Workflows]
    Q6 -->|No| Q7{Agent learning<br/>from feedback?}

    Q7 -->|Yes| Learning[Use Learning Loops<br/>+ Skills]
    Q7 -->|No| Q8{Find relevant<br/>documents?}

    Q8 -->|Yes| Search[Use Semantic Search]
    Q8 -->|No| Q9{Multi-zone<br/>SaaS?}

    Q9 -->|Yes| Tenancy[Use Multi-Tenancy<br/>Patterns]
    Q9 -->|No| Basic[Use Basic VFS]

Feature Selection Matrix¶

Use Case Scenarios¶

Scenario 1: Simple Chatbot with Memory¶

Need: A chatbot that remembers user preferences across sessions

Use: - ✅ Memory API (store/recall user preferences) - ✅ Basic VFS (store conversation logs) - ❌ NOT needed: ReBAC (single user), Workflows, Mounts

from nexus import NexusFS, LocalBackend

backend = LocalBackend(root_path="/tmp/nexus-data")
nx = NexusFS(backend=backend, is_admin=True)

# Store user preferences
nx.memory.store("user123", "preferences", {"lang": "python", "theme": "dark"})

# Later session - recall preferences
prefs = nx.memory.retrieve("user123", "preferences")
print(prefs)  # {"lang": "python", "theme": "dark"}

Why this works: Memory API is designed for session persistence. No need for complex features.

Scenario 2: Multi-Agent Research Team¶

Need: 3 agents (Researcher, Writer, Reviewer) collaborate on reports

Use: - ✅ Agent Permissions (control who can read/write) - ✅ Memory API (each agent remembers tasks) - ✅ Basic VFS (shared workspace) - ❌ NOT needed: ReBAC (simple team), Workflows (manual coordination)

backend = LocalBackend(root_path="/tmp/nexus-data")
nx = NexusFS(backend=backend, is_admin=True)

# Create agents
nx.admin.create_user("agent-researcher", subject_type="agent")
nx.admin.create_user("agent-writer", subject_type="agent")
nx.admin.create_user("agent-reviewer", subject_type="agent")

# Grant permissions
nx.rebac.grant("agent-researcher", "reader", "file", "/workspace/research")
nx.rebac.grant("agent-writer", "owner", "file", "/workspace/research")
nx.rebac.grant("agent-reviewer", "reader", "file", "/workspace/research")

# Researcher reads, Writer writes, Reviewer reviews

Why this works: Agent Permissions handles simple role-based access. Lightweight and easy to debug.

Scenario 3: Document Processing Pipeline¶

Need: Auto-process uploaded PDFs, extract text, store in database

Use: - ✅ Workflows (trigger on PDF upload) - ✅ Mounts (S3 for PDFs, PostgreSQL for extracted text) - ❌ NOT needed: Memory (stateless processing), ReBAC (single agent)

# Mount S3 for uploads
nx.mount("/workspace/uploads", S3Backend(bucket="my-bucket"))

# Mount PostgreSQL for extracted text
nx.mount("/workspace/db", PostgreSQLBackend(db="documents"))

# Create workflow
nx.workflows.create(
    name="pdf-processor",
    trigger="write:/workspace/uploads/*.pdf",
    action=lambda event: process_pdf(event.path)
)

def process_pdf(pdf_path: str):
    # Extract text from PDF
    text = extract_text(nx.read(pdf_path))

    # Store in database
    nx.write(f"/workspace/db/extracted/{pdf_path.split('/')[-1]}.txt", text.encode())

Why this works: Workflows enable event-driven automation. Mounts abstract storage backends.

Scenario 4: Enterprise Multi-Tenant SaaS¶

Need: 100 customers, each with isolated workspaces, agents, and permissions

Use: - ✅ Multi-Tenancy Patterns (tenant isolation) - ✅ ReBAC (complex org hierarchies per tenant) - ✅ Memory API (tenant-scoped memory) - ✅ Mounts (per-tenant databases) - ✅ Workflows (tenant-scoped automation)

# Tenant A: Create workspace
nx.mount("/workspace/tenant-a", PostgreSQLBackend(db="tenant_a"))
nx.rebac.create_namespace("tenant:tenant-a")

# Tenant A: Create agents
nx.admin.create_user("agent-a1", subject_type="agent")
nx.rebac.grant("agent-a1", "owner", "file", "/workspace/tenant-a/*")

# Tenant A: Isolated memory
nx.memory.store(
    identity="agent-a1",
    key="preferences",
    value={"model": "gpt-4"},
    namespace="tenant:tenant-a"
)

# Tenant B: Completely isolated (same pattern)
nx.mount("/workspace/tenant-b", PostgreSQLBackend(db="tenant_b"))
nx.rebac.create_namespace("tenant:tenant-b")

Why this works: Multi-tenancy ensures complete isolation. ReBAC handles complex permissions. Mounts provide per-tenant storage.

Scenario 5: AI Agent that Improves Over Time¶

Need: Code review agent that learns from developer feedback

Use: - ✅ Learning Loops (track feedback) - ✅ Skills (versioned review capabilities) - ✅ Memory API (remember code patterns) - ❌ NOT needed: Workflows (feedback is manual), Multi-Tenancy (single team)

# Create skill for code review
skill = nx.skills.create("code-reviewer", version="1.0")

# Agent performs review
review_result = agent.review_code("/workspace/src/app.py")

# Developer gives feedback
nx.learning.record_feedback(
    agent_id="agent-code-reviewer",
    task_id="review-123",
    feedback_type="thumbs_down",
    correction="Missed null pointer check on line 45"
)

# Agent retrieves feedback for next review
feedback_history = nx.learning.get_feedback(agent_id="agent-code-reviewer")

# Update skill with learned patterns
nx.skills.update("code-reviewer", version="1.1", improvements=feedback_history)

Why this works: Learning Loops track feedback over time. Skills version improvements.

Feature Comparison¶

Memory vs. Basic VFS¶

Example:

# Memory API: Agent remembers user preference
nx.memory.store("user123", "theme", "dark")
theme = nx.memory.retrieve("user123", "theme")  # "dark"

# Basic VFS: Store conversation log
nx.write("/workspace/user123/conversations/2024-01-01.txt", b"User said: Hello")
log = nx.read("/workspace/user123/conversations/2024-01-01.txt")

Decision: Use Memory API for ephemeral, session-based data. Use VFS for persistent files.

Agent Permissions vs. ReBAC¶

Example:

# Agent Permissions: Simple role assignment
nx.rebac.grant("agent1", "reader", "file", "/workspace/docs")
nx.rebac.grant("agent2", "owner", "file", "/workspace/docs")

# ReBAC: Complex org hierarchy
nx.rebac.create_namespace("org:engineering")
nx.rebac.grant("user:alice", "admin", "namespace", "org:engineering")
nx.rebac.grant("team:backend", "member", "namespace", "org:engineering")
nx.rebac.grant("agent1", "member", "team", "team:backend")

Decision: Start with Agent Permissions. Upgrade to ReBAC when you need hierarchies (teams, departments, groups).

Workflows vs. Polling¶

Example:

# Workflows: Trigger on file write (real-time)
nx.workflows.create(
    trigger="write:/workspace/uploads/*.csv",
    action=lambda event: process_csv(event.path)
)

# Polling: Check every 5 minutes (delayed)
import time
while True:
    files = nx.ls("/workspace/uploads", pattern="*.csv")
    for file in files:
        process_csv(file)
    time.sleep(300)  # 5 minutes

Decision: Use Workflows for real-time automation. Use polling for scheduled batch jobs.

Semantic Search vs. Grep/Glob¶

Example:

# Semantic Search: Find by meaning
results = nx.semantic_search(
    "/workspace/docs",
    query="How do I authenticate users?"
)
# Returns: ["auth-guide.md", "oauth-setup.md", "jwt-tutorial.md"]

# Grep: Find by pattern
files = nx.search.grep("/workspace/docs", pattern="def authenticate")
# Returns: Files containing exact string "def authenticate"

# Glob: Find by file pattern
files = nx.glob("/workspace/docs/**/*auth*.md")
# Returns: ["oauth-guide.md", "auth-setup.md"]

Decision: Use Semantic Search for natural language queries. Use Grep/Glob for precise pattern matching.

Mounts vs. Single Backend¶

Example:

# Mounts: Route paths to different backends
nx.mount("/workspace/local", LocalBackend())
nx.mount("/workspace/s3", S3Backend(bucket="my-bucket"))
nx.mount("/workspace/db", PostgreSQLBackend(db="nexus"))

# Write to S3
nx.write("/workspace/s3/report.pdf", pdf_bytes)

# Query database as file
nx.read("/workspace/db/users/123")  # Returns user record as JSON

# Single Backend: All data in local filesystem
backend = LocalBackend(root_path="/tmp/nexus-data")
nx = NexusFS(backend=backend, is_admin=True)  # Defaults to local
nx.write("/workspace/report.pdf", pdf_bytes)

Decision: Use Mounts when you need hybrid storage (cloud + local + database). Use single backend for simple deployments.

Decision Flowchart by Use Case¶

Use Case: Building a Chatbot¶

graph TD
    Start[Building a Chatbot] --> Q1{Multi-user?}
    Q1 -->|No| Q2{Needs memory?}
    Q1 -->|Yes| Multi[Use Memory API<br/>+ Multi-Tenancy]

    Q2 -->|Yes| Memory[Use Memory API]
    Q2 -->|No| Basic[Use Basic VFS]

    Memory --> Q3{Cloud storage?}
    Q3 -->|Yes| S3[Add S3 Mount]
    Q3 -->|No| Done1[Done!]

    S3 --> Done2[Done!]
    Multi --> Done3[Done!]

Use Case: Building Multi-Agent System¶

graph TD
    Start[Multi-Agent System] --> Q1{Team size?}
    Q1 -->|2-5 agents| Simple[Agent Permissions]
    Q1 -->|10+ agents| Complex[ReBAC]

    Simple --> Q2{Shared workspace?}
    Q2 -->|Yes| VFS[Use Basic VFS]
    Q2 -->|No| Isolated[Use Multi-Tenancy]

    Complex --> Q3{Hierarchies?}
    Q3 -->|Yes| Namespaces[Use ReBAC Namespaces]
    Q3 -->|No| Flat[Use ReBAC (flat)]

    VFS --> Done1[Done!]
    Isolated --> Done2[Done!]
    Namespaces --> Done3[Done!]
    Flat --> Done4[Done!]

Use Case: Building Data Pipeline¶

graph TD
    Start[Data Pipeline] --> Q1{Event-driven?}
    Q1 -->|Yes| Workflows[Use Workflows]
    Q1 -->|No| Cron[Use Polling/Cron]

    Workflows --> Q2{Multiple storage?}
    Q2 -->|Yes| Mounts[Add Mounts<br/>S3, DB, etc.]
    Q2 -->|No| Local[Use Local FS]

    Mounts --> Done1[Done!]
    Local --> Done2[Done!]
    Cron --> Done3[Done!]

Common Patterns¶

Pattern 1: Simple Agent (No Collaboration)¶

Use: - Basic VFS - Memory API (optional, for session persistence)

backend = LocalBackend(root_path="/tmp/nexus-data")
nx = NexusFS(backend=backend, is_admin=True)
nx.write("/workspace/data.txt", b"Hello")
nx.memory.store("agent1", "state", {"step": 1})

Don't use: ReBAC, Workflows, Multi-Tenancy

Pattern 2: Multi-Agent Collaboration (Small Team)¶

Use: - Agent Permissions - Memory API (per-agent memory) - Basic VFS (shared workspace)

nx.admin.create_user("agent1", subject_type="agent")
nx.admin.create_user("agent2", subject_type="agent")
nx.rebac.grant("agent1", "reader", "file", "/workspace/shared")
nx.rebac.grant("agent2", "owner", "file", "/workspace/shared")

Don't use: ReBAC (overkill for small teams)

Pattern 3: Multi-Agent Org (Large Team)¶

Use: - ReBAC (with namespaces) - Memory API (namespace-scoped) - Mounts (separate team storage)

nx.rebac.create_namespace("team:backend")
nx.rebac.create_namespace("team:frontend")
nx.rebac.grant("user:alice", "admin", "namespace", "team:backend")
nx.mount("/workspace/backend", S3Backend(bucket="backend-team"))
nx.mount("/workspace/frontend", S3Backend(bucket="frontend-team"))

Don't use: Simple Agent Permissions (too limited)

Pattern 4: SaaS Multi-Tenant¶

Use: - Multi-Tenancy Patterns - ReBAC (per-tenant namespaces) - Mounts (per-tenant databases) - Memory API (tenant-scoped) - Workflows (tenant-scoped)

# Per tenant
nx.mount(f"/workspace/{zone_id}", PostgreSQLBackend(db=f"tenant_{zone_id}"))
nx.rebac.create_namespace(f"tenant:{zone_id}")
nx.memory.store("agent1", "state", {...}, namespace=f"tenant:{zone_id}")

Don't use: Single namespace (security risk)

Pattern 5: Learning Agent¶

Use: - Learning Loops - Skills (versioned capabilities) - Memory API (remember learned patterns)

nx.learning.record_feedback("agent1", "task-123", "thumbs_down", "Missed edge case")
feedback = nx.learning.get_feedback("agent1")
nx.skills.update("code-reviewer", "1.1", improvements=feedback)

Don't use: Manual version tracking

Feature Combinations (Recommended Stacks)¶

Stack 1: Basic Agent¶

• Features: Basic VFS, Memory API
• Use case: Single-agent chatbot
• Complexity: Low

Stack 2: Multi-Agent Team¶

• Features: Agent Permissions, Memory API, Basic VFS
• Use case: Collaborative agents (2-10)
• Complexity: Medium

Stack 3: Enterprise Platform¶

• Features: ReBAC, Multi-Tenancy, Mounts, Memory API, Workflows
• Use case: Multi-zone SaaS
• Complexity: High

Stack 4: Data Pipeline¶

• Features: Workflows, Mounts, Semantic Search
• Use case: Event-driven document processing
• Complexity: Medium

Stack 5: Learning System¶

• Features: Learning Loops, Skills, Memory API, Basic VFS
• Use case: Self-improving agents
• Complexity: High

Red Flags: When You're Over-Engineering¶

🚩 Red Flag 1: Using ReBAC for Single Agent¶

Problem: Setting up namespaces, relations for one agent Fix: Use Basic VFS or simple Agent Permissions

🚩 Red Flag 2: Using Multi-Tenancy for Single User¶

Problem: Creating tenant namespaces for one customer Fix: Use Basic VFS

🚩 Red Flag 3: Using Workflows for Manual Tasks¶

Problem: Creating workflows for actions triggered manually Fix: Use direct API calls

🚩 Red Flag 4: Using Semantic Search for Exact Matches¶

Problem: Embedding "auth.py" to find file named "auth.py" Fix: Use Glob (nx.glob("**/auth.py"))

🚩 Red Flag 5: Using Mounts for Single Backend¶

Problem: Mounting local FS to /workspace/local Fix: Use Basic VFS (defaults to local)

Migration Paths¶

From Basic VFS → Mounts¶

When: Need cloud storage or databases

# Before
backend = LocalBackend(root_path="/tmp/nexus-data")
nx = NexusFS(backend=backend, is_admin=True)
nx.write("/workspace/data.txt", b"...")

# After
nx.mount("/workspace/s3", S3Backend(bucket="my-bucket"))
nx.write("/workspace/s3/data.txt", b"...")  # Now in S3

From Agent Permissions → ReBAC¶

When: Need hierarchies (teams, departments)

# Before
nx.rebac.grant("agent1", "reader", "file", "/workspace/docs")

# After
nx.rebac.create_namespace("team:engineering")
nx.rebac.grant("agent1", "member", "team", "team:engineering")
nx.rebac.grant("team:engineering", "reader", "file", "/workspace/docs")

From Polling → Workflows¶

When: Need real-time automation

# Before (polling every 5 mins)
while True:
    files = nx.ls("/workspace/uploads")
    for file in files:
        process(file)
    time.sleep(300)

# After (event-driven)
nx.workflows.create(
    trigger="write:/workspace/uploads/*",
    action=lambda event: process(event.path)
)

FAQ¶

Q: Should I use Memory API or just write files?¶

A: Use Memory API for session-based data (user preferences, agent state). Use files for persistent documents (reports, logs).

Q: When do I need ReBAC vs. simple permissions?¶

A: Use ReBAC when you have >10 agents or need hierarchies (teams, groups). Otherwise, Agent Permissions suffice.

Q: Can I mix local and cloud storage?¶

A: Yes! Use Mounts. Example: /workspace/local/* → Local FS, /workspace/s3/* → S3.

Q: Should I use Workflows or cron jobs?¶

A: Use Workflows for real-time triggers (file uploads). Use cron for scheduled batch jobs (nightly reports).

Q: Do I need Multi-Tenancy for 2-3 customers?¶

A: No, but it's good to start with tenant-scoped paths (e.g., /workspace/customer1/) to ease future migration.

Next Steps¶

• What is Nexus? - Understand core concepts
• Memory System - Deep dive on Memory API
• Agent Permissions - Set up multi-agent teams
• Mounts & Backends - Configure hybrid storage
• Multi-Tenancy - Build multi-zone SaaS

For hands-on examples: - Quick Start Guide - 5-minute tutorial - Learning Paths - Structured tutorials - Examples - Real-world use cases