# Architecture Documentation

This document provides comprehensive technical diagrams and explanations of the Nexus Memory system architecture.

## Table of Contents

1. [System Architecture Overview](#1-system-architecture-overview)
2. [Data Flow Diagram](#2-data-flow-diagram)
3. [Memory Type Hierarchy](#3-memory-type-hierarchy)
4. [Integration Ecosystem](#4-integration-ecosystem)
5. [GraphRAG vs Traditional RAG](#5-graphrag-vs-traditional-rag)
6. [Three-Tier Memory Model](#6-three-tier-memory-model)
7. [Hook Execution Sequence](#7-hook-execution-sequence)
8. [Multi-Agent Memory Sharing](#8-multi-agent-memory-sharing)
9. [Enterprise Deployment Topology](#9-enterprise-deployment-topology)
10. [Component Interaction Details](#10-component-interaction-details)

---

## 1. System Architecture Overview

The complete Nexus Memory architecture from Claude Code to persistent storage.

```mermaid
graph TB
    subgraph "Developer Environment"
        DEV[Developer] --> CC[Claude Code]
        CC --> SK[Nexus Memory Skill]
        SK --> |invoke| H1[store-memory.sh]
        SK --> |invoke| H2[recall-memory.sh]
        SK --> |invoke| H3[upload-document.sh]
    end

    subgraph "Transport Layer"
        H1 --> |HTTPS POST| GW
        H2 --> |HTTPS POST| GW
        H3 --> |HTTPS POST| GW
        GW[API Gateway<br/>api.adverant.ai]
    end

    subgraph "Nexus Platform"
        GW --> AUTH[Authentication<br/>X-Company-ID, X-App-ID, X-User-ID]
        AUTH --> ROUTER[Request Router]

        ROUTER --> |/api/memory/store| MS[Memory Service]
        ROUTER --> |/api/memory/recall| RS[Recall Service]
        ROUTER --> |/api/documents/store| DS[Document Service]

        MS --> GR[GraphRAG Engine]
        RS --> GR
        DS --> GR
    end

    subgraph "Storage Layer"
        GR --> KG[(Knowledge Graph<br/>Neo4j)]
        GR --> VDB[(Vector Database<br/>Embeddings)]
        GR --> META[(Metadata Store<br/>PostgreSQL)]
    end

    style DEV fill:#e1f5fe
    style GW fill:#fff3e0
    style GR fill:#f3e5f5
    style KG fill:#e8f5e9
    style VDB fill:#e8f5e9
    style META fill:#e8f5e9
```

### Key Components

| Component | Purpose | Technology |
|-----------|---------|------------|
| **Claude Code** | AI development environment | Anthropic Claude |
| **Nexus Memory Skill** | Skill integration layer | Bash scripts |
| **API Gateway** | Request routing & auth | HTTPS/REST |
| **GraphRAG Engine** | Knowledge graph + RAG | Custom ML pipeline |
| **Knowledge Graph** | Entity & relationship storage | Neo4j |
| **Vector Database** | Semantic embeddings | Pinecone/Weaviate |
| **Metadata Store** | Temporal & context data | PostgreSQL |

---

## 2. Data Flow Diagram

How data moves through the system during store and recall operations.

```mermaid
sequenceDiagram
    participant D as Developer
    participant CC as Claude Code
    participant SK as Skill
    participant H as Hook Script
    participant GW as API Gateway
    participant GR as GraphRAG
    participant KG as Knowledge Graph
    participant VDB as Vector DB

    Note over D,VDB: Store Memory Flow
    D->>CC: "Store this fix..."
    CC->>SK: Invoke nexus-memory
    SK->>H: store-memory.sh
    H->>GW: POST /api/memory/store
    GW->>GR: Process content

    par Entity Extraction
        GR->>GR: Extract entities
        GR->>GR: Identify relationships
    and Embedding Generation
        GR->>GR: Generate embeddings
    end

    GR->>KG: Store entities & relations
    GR->>VDB: Store embeddings
    GR-->>GW: Success
    GW-->>H: 200 OK
    H-->>SK: Stored
    SK-->>CC: Memory saved
    CC-->>D: "Saved to memory"

    Note over D,VDB: Recall Memory Flow
    D->>CC: "What was that fix for..."
    CC->>SK: Invoke nexus-memory
    SK->>H: recall-memory.sh
    H->>GW: POST /api/memory/recall
    GW->>GR: Process query

    par Vector Search
        GR->>VDB: Semantic search
        VDB-->>GR: Similar memories
    and Graph Traversal
        GR->>KG: Entity lookup
        KG-->>GR: Related nodes
    end

    GR->>GR: Multi-hop reasoning
    GR->>GR: Rank & filter results
    GR-->>GW: Memories + context
    GW-->>H: JSON response
    H-->>SK: Parsed results
    SK-->>CC: Relevant memories
    CC-->>D: "Here's what I found..."
```

---

## 3. Memory Type Hierarchy

The cognitive architecture of Nexus Memory, inspired by human memory systems.

```mermaid
graph TB
    subgraph "Memory Architecture"
        ROOT[Nexus Memory System]

        ROOT --> EP[Episodic Memory<br/>What happened]
        ROOT --> SEM[Semantic Memory<br/>What we know]
        ROOT --> PROC[Procedural Memory<br/>How to do things]
        ROOT --> TEMP[Temporal Memory<br/>When & why]

        subgraph "Episodic (Events)"
            EP --> E1[Session logs]
            EP --> E2[Conversation history]
            EP --> E3[Tool executions]
            EP --> E4[Error occurrences]
        end

        subgraph "Semantic (Facts)"
            SEM --> S1[Bug fixes]
            SEM --> S2[Architecture decisions]
            SEM --> S3[Project configurations]
            SEM --> S4[Dependencies]
        end

        subgraph "Procedural (How-to)"
            PROC --> P1[Code patterns]
            PROC --> P2[Build processes]
            PROC --> P3[Deployment steps]
            PROC --> P4[Testing strategies]
        end

        subgraph "Temporal (Context)"
            TEMP --> T1[Decision timestamps]
            TEMP --> T2[Causal chains]
            TEMP --> T3[Version history]
            TEMP --> T4[Evolution tracking]
        end
    end

    style ROOT fill:#1565c0,color:#fff
    style EP fill:#7b1fa2,color:#fff
    style SEM fill:#388e3c,color:#fff
    style PROC fill:#f57c00,color:#fff
    style TEMP fill:#d32f2f,color:#fff
```

### Memory Type Mapping

| Event Type | Memory Category | Retention | Search Priority |
|------------|-----------------|-----------|-----------------|
| `fix` | Semantic | Permanent | High |
| `decision` | Semantic + Temporal | Permanent | High |
| `learning` | Semantic | Permanent | Medium |
| `pattern` | Procedural | Permanent | High |
| `preference` | Semantic | Permanent | Medium |
| `context` | Episodic | Session-linked | Low |

---

## 4. Integration Ecosystem

Current and planned integrations for the Nexus Memory platform.

```mermaid
graph TB
    subgraph "Core Platform"
        NM[Nexus Memory<br/>GraphRAG Engine]
    end

    subgraph "AI Assistants"
        CC[Claude Code] --> NM
        CLAUDE[Claude Chat] -.-> NM
        GPT[OpenAI GPT] -.-> NM
        LOCAL[Local LLMs] -.-> NM
    end

    subgraph "Development Tools"
        NM --> VSC[VS Code Extension]
        NM --> JB[JetBrains Plugin]
        NM --> VIM[Vim/Neovim]
        NM --> TERM[Terminal CLI]
    end

    subgraph "Version Control"
        GIT[Git Hooks] --> NM
        GHA[GitHub Actions] --> NM
        GL[GitLab CI] -.-> NM
    end

    subgraph "Communication"
        SLACK[Slack Bot] -.-> NM
        DISCORD[Discord Bot] -.-> NM
        TEAMS[MS Teams] -.-> NM
    end

    subgraph "Knowledge Sources"
        NM --> DOCS[Documentation]
        NM --> CODE[Codebase]
        NM --> WEB[Web Research]
        NM --> API[API Specs]
    end

    subgraph "Protocols"
        MCP[Model Context Protocol] --> NM
        REST[REST API] --> NM
        WS[WebSocket] -.-> NM
        GRPC[gRPC] -.-> NM
    end

    style NM fill:#1565c0,color:#fff
    style CC fill:#388e3c,color:#fff

    %% Solid lines = implemented
    %% Dashed lines = planned
```

### Integration Status

| Integration | Status | Priority | ETA |
|-------------|--------|----------|-----|
| Claude Code | ✅ Available | - | - |
| VS Code Extension | 🚧 Planned | High | Q2 2025 |
| JetBrains Plugin | 🚧 Planned | High | Q2 2025 |
| Git Hook Integration | 🚧 Planned | High | Q2 2025 |
| MCP Server Mode | 🚧 Planned | High | Q1 2025 |
| Slack Bot | 📋 Backlog | Medium | Q3 2025 |
| Browser Extension | 📋 Backlog | Medium | Q2 2025 |

---

## 5. GraphRAG vs Traditional RAG

Understanding why GraphRAG is superior for AI memory systems.

```mermaid
graph TB
    subgraph "Traditional RAG"
        Q1[Query] --> E1[Embed Query]
        E1 --> VS1[Vector Search]
        VS1 --> TOP[Top-K Results]
        TOP --> LLM1[LLM Generation]

        D1[Documents] --> C1[Chunk]
        C1 --> E2[Embed Chunks]
        E2 --> VDB1[(Vector DB)]
        VDB1 --> VS1
    end

    subgraph "GraphRAG (Nexus Memory)"
        Q2[Query] --> E3[Embed Query]
        Q2 --> NER[Named Entity Recognition]

        E3 --> VS2[Vector Search]
        NER --> GL[Graph Lookup]

        VS2 --> FUSE[Fusion Layer]
        GL --> FUSE

        FUSE --> MH[Multi-Hop Reasoning]
        MH --> RANK[Relevance Ranking]
        RANK --> LLM2[LLM Generation]

        D2[Documents] --> EE[Entity Extraction]
        EE --> RE[Relationship Extraction]
        RE --> KG2[(Knowledge Graph)]

        D2 --> C2[Chunk]
        C2 --> E4[Embed Chunks]
        E4 --> VDB2[(Vector DB)]

        KG2 --> GL
        VDB2 --> VS2
    end

    style Q1 fill:#ffcdd2
    style Q2 fill:#c8e6c9
    style FUSE fill:#fff9c4
    style MH fill:#b3e5fc
```

### Performance Comparison

| Capability | Traditional RAG | GraphRAG |
|------------|:---------------:|:--------:|
| Simple Q&A | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Multi-hop reasoning | ⭐ | ⭐⭐⭐⭐⭐ |
| Entity relationships | ⭐ | ⭐⭐⭐⭐⭐ |
| Temporal queries | ⭐ | ⭐⭐⭐⭐ |
| Context preservation | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| Disambiguation | ⭐⭐ | ⭐⭐⭐⭐ |
| Explainability | ⭐⭐ | ⭐⭐⭐⭐⭐ |

---

## 6. Three-Tier Memory Model

The cognitive-inspired memory hierarchy.

```mermaid
graph TB
    subgraph "Working Memory"
        WM[Working Memory<br/>Seconds - Minutes]
        WM1[Current session context]
        WM2[Active reasoning workspace]
        WM3[Immediate task focus]
        WM --> WM1
        WM --> WM2
        WM --> WM3
    end

    subgraph "Short-Term Memory"
        STM[Short-Term Memory<br/>Minutes - Hours]
        STM1[Session history]
        STM2[Recent interactions]
        STM3[Temporary context]
        STM --> STM1
        STM --> STM2
        STM --> STM3
    end

    subgraph "Long-Term Memory"
        LTM[Long-Term Memory<br/>Permanent]
        LTM1[Fixes & solutions]
        LTM2[Architecture decisions]
        LTM3[Learned patterns]
        LTM4[User preferences]
        LTM --> LTM1
        LTM --> LTM2
        LTM --> LTM3
        LTM --> LTM4
    end

    WM --> |consolidate| STM
    STM --> |persist| LTM
    LTM --> |recall| WM

    style WM fill:#ffecb3
    style STM fill:#b3e5fc
    style LTM fill:#c8e6c9
```

### Memory Characteristics

| Tier | Capacity | Latency | Persistence | Use Case |
|------|----------|---------|-------------|----------|
| **Working** | Limited (~8 items) | <10ms | Session only | Active reasoning |
| **Short-Term** | Medium (~100 items) | <50ms | Hours | Recent context |
| **Long-Term** | Unlimited | <200ms | Permanent | Institutional knowledge |

---

## 7. Hook Execution Sequence

Detailed view of how shell hooks execute.

```mermaid
sequenceDiagram
    participant SK as Skill (SKILL.md)
    participant SH as store-memory.sh
    participant JQ as jq (JSON Parser)
    participant CURL as curl (HTTP Client)
    participant GW as API Gateway

    Note over SK,GW: Store Memory Hook Execution

    SK->>SH: echo '{"content": "...", "event_type": "fix"}' | store-memory.sh

    activate SH
    SH->>SH: Read stdin into $INPUT

    SH->>JQ: Extract content
    JQ-->>SH: $CONTENT

    SH->>JQ: Extract session_id
    JQ-->>SH: $SESSION_ID

    SH->>JQ: Extract event_type
    JQ-->>SH: $EVENT_TYPE

    SH->>SH: Get $PROJECT_DIR (pwd)
    SH->>SH: Get $PROJECT_NAME (basename)

    alt Content is empty
        SH-->>SK: exit 0 (skip)
    else Content exists
        SH->>SH: Build JSON payload

        Note over SH,CURL: Async execution (background)
        SH->>CURL: POST /api/memory/store

        activate CURL
        CURL->>GW: HTTPS Request
        Note right of CURL: Headers:<br/>X-Company-ID<br/>X-App-ID<br/>X-User-ID

        GW-->>CURL: 200 OK (or error)
        CURL-->>SH: Response (discarded)
        deactivate CURL

        SH-->>SK: exit 0
    end
    deactivate SH
```

### Hook Parameters

| Parameter | Source | Default | Description |
|-----------|--------|---------|-------------|
| `NEXUS_API_URL` | Environment | `https://api.adverant.ai` | API endpoint |
| `COMPANY_ID` | Hardcoded | `adverant` | Tenant identifier |
| `APP_ID` | Hardcoded | `claude-code` | Application identifier |
| `USER` | Environment | `unknown` | User identifier |
| `PROJECT_DIR` | `pwd` | Current directory | Project path |
| `PROJECT_NAME` | `basename` | Directory name | Project name |

---

## 8. Multi-Agent Memory Sharing

How multiple AI agents can share knowledge through Nexus Memory.

```mermaid
graph TB
    subgraph "Team Environment"
        DEV1[Developer A<br/>Claude Code] --> |store| NM
        DEV2[Developer B<br/>Claude Code] --> |store| NM
        DEV3[Developer C<br/>Claude Code] --> |store| NM
    end

    subgraph "Shared Memory Layer"
        NM[Nexus Memory<br/>GraphRAG]

        NM --> |team:alpha| TM1[Team Memory Pool]
        NM --> |project:nexus| PM1[Project Memory]
        NM --> |user:alice| UM1[Personal Memory]
    end

    subgraph "Memory Access Patterns"
        TM1 --> |read/write| DEV1
        TM1 --> |read/write| DEV2
        TM1 --> |read/write| DEV3

        PM1 --> |read/write| DEV1
        PM1 --> |read/write| DEV2

        UM1 --> |read/write| DEV1
    end

    subgraph "Cross-Agent Benefits"
        B1[Bug fix by Dev A<br/>→ Available to Dev B]
        B2[Pattern by Dev B<br/>→ Available to all]
        B3[Decision by Dev C<br/>→ Documented for team]
    end

    style NM fill:#1565c0,color:#fff
    style TM1 fill:#388e3c,color:#fff
    style PM1 fill:#f57c00,color:#fff
    style UM1 fill:#7b1fa2,color:#fff
```

### Access Control Model

| Scope | Visibility | Write Access | Use Case |
|-------|------------|--------------|----------|
| **Personal** | Individual only | Owner only | Preferences, experiments |
| **Project** | Project team | Project members | Architecture, conventions |
| **Team** | Organization | Team members | Institutional knowledge |
| **Global** | All users | System only | Best practices |

---

## 9. Enterprise Deployment Topology

Production-ready deployment architecture.

```mermaid
graph TB
    subgraph "Client Layer"
        C1[Claude Code<br/>Developer 1]
        C2[Claude Code<br/>Developer 2]
        C3[CI/CD Pipeline]
    end

    subgraph "Edge Layer"
        LB[Load Balancer<br/>HAProxy/nginx]
        CDN[CDN<br/>Static Assets]
    end

    subgraph "API Layer"
        GW1[API Gateway 1]
        GW2[API Gateway 2]
        GW3[API Gateway 3]
    end

    subgraph "Service Layer"
        subgraph "Memory Services"
            MS1[Memory Service 1]
            MS2[Memory Service 2]
        end

        subgraph "GraphRAG Cluster"
            GR1[GraphRAG Node 1]
            GR2[GraphRAG Node 2]
            GR3[GraphRAG Node 3]
        end
    end

    subgraph "Data Layer"
        subgraph "Primary"
            KG_P[(Knowledge Graph<br/>Primary)]
            VDB_P[(Vector DB<br/>Primary)]
            META_P[(Metadata<br/>Primary)]
        end

        subgraph "Replica"
            KG_R[(Knowledge Graph<br/>Replica)]
            VDB_R[(Vector DB<br/>Replica)]
            META_R[(Metadata<br/>Replica)]
        end
    end

    subgraph "Infrastructure"
        CACHE[Redis Cache]
        QUEUE[Message Queue<br/>RabbitMQ]
        MONITOR[Monitoring<br/>Prometheus/Grafana]
    end

    C1 --> LB
    C2 --> LB
    C3 --> LB

    LB --> GW1
    LB --> GW2
    LB --> GW3

    GW1 --> MS1
    GW2 --> MS1
    GW3 --> MS2

    MS1 --> GR1
    MS1 --> GR2
    MS2 --> GR2
    MS2 --> GR3

    GR1 --> KG_P
    GR2 --> VDB_P
    GR3 --> META_P

    KG_P --> KG_R
    VDB_P --> VDB_R
    META_P --> META_R

    MS1 --> CACHE
    MS2 --> CACHE
    GR1 --> QUEUE
    GR2 --> QUEUE
    GR3 --> QUEUE

    style LB fill:#ff9800,color:#fff
    style GR1 fill:#9c27b0,color:#fff
    style GR2 fill:#9c27b0,color:#fff
    style GR3 fill:#9c27b0,color:#fff
```

### Deployment Specifications

| Component | Instances | Resources | HA Strategy |
|-----------|-----------|-----------|-------------|
| API Gateway | 3+ | 2 CPU, 4GB RAM | Active-Active |
| Memory Service | 2+ | 4 CPU, 8GB RAM | Active-Active |
| GraphRAG Node | 3+ | 8 CPU, 32GB RAM | Active-Active |
| Knowledge Graph | 1 Primary + 1 Replica | 16 CPU, 64GB RAM | Primary-Replica |
| Vector DB | 1 Primary + 1 Replica | 8 CPU, 32GB RAM | Primary-Replica |
| Redis Cache | 3 (Sentinel) | 4 CPU, 16GB RAM | Sentinel |

---

## 10. Component Interaction Details

Detailed view of component responsibilities and interactions.

```mermaid
classDiagram
    class ClaudeCode {
        +Session session
        +Context context
        +invokeSkill(name)
        +sendMessage(content)
    }

    class NexusMemorySkill {
        +String name
        +String description
        +String[] allowedTools
        +storeMemory(content, type)
        +recallMemory(query)
        +uploadDocument(path, title)
    }

    class StoreMemoryHook {
        +String NEXUS_API_URL
        +String COMPANY_ID
        +String APP_ID
        +parseInput(stdin)
        +buildPayload()
        +sendAsync()
    }

    class RecallMemoryHook {
        +String NEXUS_API_URL
        +String COMPANY_ID
        +String APP_ID
        +parseInput(stdin)
        +buildQuery()
        +sendSync()
        +formatResponse()
    }

    class APIGateway {
        +authenticate(headers)
        +route(request)
        +rateLimit(client)
        +log(request, response)
    }

    class GraphRAGEngine {
        +extractEntities(content)
        +identifyRelationships(entities)
        +generateEmbeddings(content)
        +searchVector(query)
        +traverseGraph(entity)
        +rankResults(candidates)
    }

    class KnowledgeGraph {
        +createNode(entity)
        +createEdge(from, to, relation)
        +queryNodes(pattern)
        +traversePath(start, depth)
    }

    class VectorDatabase {
        +storeEmbedding(id, vector)
        +search(query, topK)
        +delete(id)
    }

    ClaudeCode --> NexusMemorySkill : invokes
    NexusMemorySkill --> StoreMemoryHook : uses
    NexusMemorySkill --> RecallMemoryHook : uses
    StoreMemoryHook --> APIGateway : HTTP POST
    RecallMemoryHook --> APIGateway : HTTP POST
    APIGateway --> GraphRAGEngine : routes
    GraphRAGEngine --> KnowledgeGraph : stores/queries
    GraphRAGEngine --> VectorDatabase : stores/searches
```

---

## Summary

Nexus Memory provides a sophisticated, production-ready architecture for AI memory that:

1. **Scales** from individual developer to enterprise teams
2. **Persists** knowledge across sessions and projects
3. **Connects** related concepts through knowledge graphs
4. **Reasons** temporally about when and why decisions were made
5. **Integrates** seamlessly with Claude Code and future LLM tools

For implementation details, see:
- [API Reference](api-reference.md)
- [Integration Guide](integration-guide.md)
- [Getting Started](getting-started.md)