Nexus Memory

Give Your AI Perfect Recall — Across Every Session, Every Project, Forever

The open-source memory layer for Claude Code that remembers what you learned, why you decided, and how you solved it.

Quick Start · Documentation · Use Cases · Roadmap · Contributing

The Problem

Every time you start a new Claude Code session, your AI assistant forgets everything:

• The bug fix you spent 2 hours debugging last week? Gone.
• The architecture decision and why you made it? Vanished.
• Your coding preferences and project conventions? Reset.
• The patterns you discovered in another repository? Isolated.

You're teaching your AI the same lessons over and over again. That's not intelligence — that's amnesia.

The Solution

Nexus Memory gives Claude Code a persistent, searchable, cross-project memory powered by GraphRAG technology.

# Store a learning
echo '{"content": "ESLint flat config requires explicit plugin imports", "event_type": "learning"}' \
  | ~/.claude/hooks/store-memory.sh

# Recall it months later, in any project
echo '{"query": "ESLint configuration"}' | ~/.claude/hooks/recall-memory.sh

Your AI now remembers:

• Fixes — Never solve the same bug twice
• Decisions — Remember why you chose that architecture
• Patterns — Learn once, apply everywhere
• Preferences — Your coding style, enforced automatically
• Context — Project-specific knowledge that persists

Why Nexus Memory?

What Makes It Different

| Feature | Nexus Memory | Others | |---------|:------------:|:------:| | Cross-project memory | ✅ | ❌ | | GraphRAG powered | ✅ | ❌ | | Temporal reasoning | ✅ | ❌ | | Zero cost | ✅ | 💰 | | Open source | ✅ | ⚠️ | | Claude Code native | ✅ | ❌ |

The Technology

Unlike simple vector search, GraphRAG (Graph-based Retrieval Augmented Generation) creates a knowledge graph of your memories:

• Entities are extracted and linked
• Relationships between concepts are mapped
• Temporal context tracks when and why
• Semantic search finds relevant memories
• Multi-hop reasoning connects the dots

Competitive Comparison

| Capability | Nexus Memory | Mem0 | Zep AI | Claude Built-in | LangChain | |------------|:------------:|:----:|:------:|:---------------:|:---------:| | Cross-project memory | ✅ | ❌ | ❌ | ❌ | ❌ | | Knowledge graph storage | ✅ | ❌ | ✅ | ❌ | ❌ | | Temporal reasoning (when/why) | ✅ | ❌ | ✅ | ❌ | ❌ | | GitHub repo ingestion | ✅ | ❌ | ❌ | ❌ | ❌ | | Claude Code integration | ✅ Native | ❌ | ❌ | ✅ Limited | ❌ | | Open source | ✅ MIT | ✅ | ⚠️ Partial | ❌ | ✅ | | Self-hosted option | ✅ | ✅ | ✅ | ❌ | ✅ | | Pricing | Free | Usage-based | Enterprise | $20+/mo | DIY | | Setup complexity | 1 command | SDK integration | API setup | Paid tier | Significant |

Bottom line: Nexus Memory is the only solution that combines GraphRAG-powered knowledge graphs with native Claude Code integration — at zero cost.

Quick Start

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/adverant/nexus-memory-skill/main/install.sh | bash

This will:

1. Install all skill files and hooks
2. Configure automatic memory (auto-recall + auto-store)
3. Open a browser to get your free API key
4. Verify everything works

Install via npm

npm install -g @adverant/nexus-memory-skill

Then run the installer:

$(npm root -g)/@adverant/nexus-memory-skill/install.sh

Install via Git

git clone https://github.com/adverant/nexus-memory-skill.git
cd nexus-memory-skill
./install.sh

Verify Installation

ls -la ~/.claude/skills/nexus-memory/SKILL.md && echo "Skill installed"
ls -la ~/.claude/hooks/auto-recall.sh && echo "Auto-recall hook installed"
ls -la ~/.claude/hooks/store-memory.sh && echo "Store hook installed"
ls -la ~/.claude/hooks/episode-summary.sh && echo "Episode summary hook installed"

Manual Installation

1. Clone the repository

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

2. Create directories

   mkdir -p ~/.claude/skills/nexus-memory ~/.claude/hooks

3. Copy skill and hooks

   cp nexus-memory-skill/SKILL.md ~/.claude/skills/nexus-memory/
   cp nexus-memory-skill/hooks/*.sh ~/.claude/hooks/
   chmod +x ~/.claude/hooks/*.sh

4. Configure settings.json for automatic memory

   cat > ~/.claude/settings.json << 'EOF'
   {
     "hooks": {
       "UserPromptSubmit": [
         {
           "matcher": "",
           "hooks": [
             {"type": "command", "command": "~/.claude/hooks/auto-recall.sh"},
             {"type": "command", "command": "~/.claude/hooks/store-memory.sh"}
           ]
         }
       ],
       "PostToolUse": [
         {
           "matcher": "",
           "hooks": [
             {"type": "command", "command": "~/.claude/hooks/store-memory.sh"},
             {"type": "command", "command": "~/.claude/hooks/episode-summary.sh"}
           ]
         }
       ]
     }
   }
   EOF

5. Get your API key

   Visit https://dashboard.adverant.ai/dashboard/api-keys and create a free API key.

6. Configure API key

   echo "export NEXUS_API_KEY='your-api-key-here'" >> ~/.zshrc
   source ~/.zshrc

Automatic Memory (Zero-Config)

Once installed, Nexus Memory works automatically with no manual intervention:

What Happens Automatically

| Event | Action | Hook | |-------|--------|------| | You send a prompt | Relevant memories, entities, and facts are recalled with enhanced context | auto-recall.sh | | You send a prompt | Your prompt is stored with entity extraction and causal chaining | store-memory.sh | | A significant tool is used | Tool inputs/outputs are captured (routine tools skipped) | episode-summary.sh | | Every 10 tool uses | Conversation segment is summarized as an "episode" with relationships | episode-summary.sh |

v2.0.0 Enhanced Memory Intelligence

Major improvements in v2.0.0:

• Content Classification — Automatically filters noise (routine commands, short content)
• Entity Extraction — Fixed bug where entities were filtered out in API responses
• Facts Retrieval — Facts are now properly queried from Neo4j knowledge graph
• Token Budget Management — Intelligent truncation to stay within context limits
• Causal Chains — Episode summaries link to previous episodes for temporal reasoning

The auto-recall now provides rich context including:

• Relevant Memories — Past fixes, decisions, and learnings (filtered for quality)
• Entities Mentioned — Knowledge graph nodes (files, functions, patterns)
• Key Facts — Extracted facts from your coding history
• Recent Session Context — Episodic memory from recent sessions
• Suggested Follow-ups — Related queries to explore

Example: Automatic Context

When you ask Claude about something you've worked on before:

You: "How did we fix that CORS issue?"

[auto-recall.sh retrieves relevant memories]

Claude: "Based on my memory, you fixed the CORS issue by adding
credentials: 'include' to fetch options in src/api/client.ts.
This was needed because the server requires cookie authentication."

No manual recall needed — relevant context is automatically provided.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | NEXUS_API_KEY | (required) | Your API key from dashboard.adverant.ai | | NEXUS_RECALL_LIMIT | 5 | Number of memories to auto-recall per prompt | | NEXUS_EPISODE_THRESHOLD | 10 | Tool uses before generating episode summary | | NEXUS_VERBOSE | 0 | Set to 1 to see debug output |

GraphRAG Enhancement Options (v1.3.0+)

| Variable | Default | Description | |----------|---------|-------------| | NEXUS_EXTRACT_ENTITIES | true | Enable entity extraction for knowledge graph | | NEXUS_CREATE_RELATIONS | true | Create relationships between memories | | NEXUS_INCLUDE_ENTITIES | true | Include entities in recall output | | NEXUS_INCLUDE_FACTS | true | Include extracted facts in recall output | | NEXUS_INCLUDE_FOLLOWUPS | true | Include suggested follow-up queries | | NEXUS_GRAPH_DEPTH | 2 | Multi-hop graph traversal depth | | NEXUS_MAX_TOKENS | 4000 | Token budget for recall responses | | NEXUS_SKIP_ROUTINE | true | Skip storing routine tool uses (Read, ls, git status) |

Manual Usage

You can also manually store and recall memories:

Store Memory

Store learnings, decisions, fixes, and patterns that persist across sessions:

# Store a bug fix
echo '{"content": "CORS errors fixed by adding credentials: include to fetch options", "event_type": "fix"}' \
  | ~/.claude/hooks/store-memory.sh

# Store an architecture decision
echo '{"content": "Chose PostgreSQL over MongoDB for ACID compliance in payment processing", "event_type": "decision"}' \
  | ~/.claude/hooks/store-memory.sh

# Store a discovered pattern
echo '{"content": "React Query invalidation requires exact key match including all parameters", "event_type": "pattern"}' \
  | ~/.claude/hooks/store-memory.sh

# Store user preferences
echo '{"content": "User prefers functional components with TypeScript strict mode", "event_type": "preference"}' \
  | ~/.claude/hooks/store-memory.sh

Recall Memory

Search your memory with natural language queries:

# Find past fixes
echo '{"query": "CORS authentication errors"}' | ~/.claude/hooks/recall-memory.sh

# Recall decisions
echo '{"query": "database selection payment system"}' | ~/.claude/hooks/recall-memory.sh

# Search patterns
echo '{"query": "React Query cache invalidation"}' | ~/.claude/hooks/recall-memory.sh

Upload Documents

Index entire documents for knowledge retrieval:

# Upload a technical spec
~/.claude/hooks/upload-document.sh ./technical-spec.md "API Technical Specification" "api,documentation"

# Upload architecture docs
~/.claude/hooks/upload-document.sh ./architecture.md "System Architecture" "architecture,design"

Ingest GitHub Repositories

Upload entire GitHub repositories into memory for code understanding:

# Ingest a repository into memory
curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "X-Company-ID: adverant" \
  -H "X-App-ID: claude-code" \
  -d '{"fileUrl": "https://github.com/owner/repo", "filename": "repo", "userId": "user"}'

This creates a "digital twin" with:

• AST Parsing — Tree-sitter extracts code structure
• Code Graphs — Neo4j stores relationships between entities
• Embeddings — Voyage AI vectors in Qdrant for semantic search
• Memory — GraphRAG episodic/semantic memory integration

After ingestion, query the repository naturally:

echo '{"query": "authentication flow in owner/repo"}' | ~/.claude/hooks/recall-memory.sh

Memory Types

| Type | Use For | Example | |------|---------|---------| | fix | Bug fixes and solutions | "ENOENT errors fixed by using path.resolve()" | | decision | Architecture/design choices | "Using Redis for session storage for horizontal scaling" | | learning | Discoveries while coding | "Prisma requires explicit disconnect in serverless" | | pattern | Reusable code patterns | "Error boundary pattern for React async components" | | preference | User/project preferences | "Prefer named exports over default exports" | | context | Project-specific knowledge | "This repo uses pnpm workspaces with Turborepo" |

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                               │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────────┐ │
│  │   Session   │───▶│ Nexus Memory │───▶│    Shell Hooks      │ │
│  │   Context   │    │    Skill     │    │ store/recall/upload │ │
│  └─────────────┘    └──────────────┘    └──────────┬──────────┘ │
└──────────────────────────────────────────────────────│──────────┘
                                                       │ HTTPS
                                                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Nexus Platform                              │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────────┐ │
│  │ API Gateway │───▶│   GraphRAG   │───▶│  Knowledge Graph    │ │
│  │   (Auth)    │    │   Engine     │    │  + Vector Database  │ │
│  └─────────────┘    └──────────────┘    └─────────────────────┘ │
│                            │                                     │
│                            ▼                                     │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Memory Types                              ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ ││
│  │  │ Episodic │  │ Semantic │  │Procedural│  │   Temporal   │ ││
│  │  │ (Events) │  │ (Facts)  │  │ (How-to) │  │ (When/Why)   │ ││
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

See Architecture Documentation for detailed diagrams.

How It Works

1. Store Phase

When you store a memory:

1. Content is sent to the Nexus API Gateway
2. GraphRAG extracts entities and relationships
3. Memory is indexed in both knowledge graph and vector database
4. Temporal metadata captures when and in what context

2. Recall Phase

When you query memories:

1. Query is semantically analyzed
2. GraphRAG traverses the knowledge graph
3. Multi-hop reasoning connects related concepts
4. Relevant memories, documents, and entities are returned

3. Integration

The skill automatically provides:

• Project context (current directory, project name)
• Session tracking (group related memories)
• Event type classification (fix, decision, learning, etc.)
• User attribution (for team scenarios)

Configuration

Environment Variables

# Override the default API endpoint (optional)
export NEXUS_API_URL="https://api.adverant.ai"

# Custom company/app context (optional)
export NEXUS_COMPANY_ID="your-company"
export NEXUS_APP_ID="claude-code"

Requirements

• curl — HTTP client (pre-installed on most systems)
• jq — JSON processor (install)
• Claude Code — With skills support enabled

Use Cases

Store bug fixes when you solve them:

echo '{"content": "Safari date parsing requires explicit timezone: new Date(dateStr + \"T00:00:00\")", "event_type": "fix"}' \
  | ~/.claude/hooks/store-memory.sh

Recall them months later:

echo '{"query": "Safari date parsing issues"}' | ~/.claude/hooks/recall-memory.sh

Document decisions with context:

echo '{"content": "Chose event sourcing over CRUD for audit trail requirements. Trade-off: more complex queries but complete history.", "event_type": "decision"}' \
  | ~/.claude/hooks/store-memory.sh

Learn a pattern in one project:

echo '{"content": "Optimistic UI updates: update state immediately, rollback on error with toast notification", "event_type": "pattern"}' \
  | ~/.claude/hooks/store-memory.sh

Apply it in another:

echo '{"query": "optimistic UI update pattern"}' | ~/.claude/hooks/recall-memory.sh

Team members store collective knowledge:

echo '{"content": "Our CI requires Node 20+ for native fetch support", "event_type": "context"}' \
  | ~/.claude/hooks/store-memory.sh

New team members instantly benefit from institutional knowledge.

Ingest an entire repository to understand its architecture:

curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "X-Company-ID: adverant" \
  -H "X-App-ID: claude-code" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl": "https://github.com/company/legacy-service", "filename": "legacy-service"}'

Then query it naturally:

echo '{"query": "how does authentication work in legacy-service"}' | ~/.claude/hooks/recall-memory.sh
echo '{"query": "database schema for users in legacy-service"}' | ~/.claude/hooks/recall-memory.sh

Perfect for:

• Onboarding — Understand unfamiliar codebases instantly
• Code Reviews — Query patterns and dependencies
• Refactoring — Find all usages across the codebase
• Documentation — Generate docs from actual code structure

See 20 detailed use cases →

Roadmap

We're building the most comprehensive AI memory system. Here's what's coming:

Q1 2025 — Core Enhancements

• [ ] MCP Server Mode — Use with any LLM
• [ ] Local-first storage — SQLite/DuckDB for offline
• [ ] Memory encryption — AES-256 for sensitive data
• [ ] Memory versioning — Git-like history

Q2 2025 — Integration Hub

• [ ] Git hook integration — Auto-capture commit context
• [ ] VS Code extension — Memory panel in IDE
• [ ] JetBrains plugin — IntelliJ/WebStorm support
• [ ] Browser extension — Capture research context

Q3 2025 — Intelligence Layer

• [ ] Memory summarization — Automatic compression
• [ ] Conflict detection — Alert on contradictions
• [ ] Memory visualization — Interactive knowledge explorer
• [ ] Predictive context — Pre-fetch relevant memories

See full roadmap →

Documentation

| Document | Description | |----------|-------------| | Architecture | System design, data flow, and component diagrams | | Use Cases | 20 detailed scenarios with code examples | | API Reference | Complete API documentation | | Integration Guide | Custom integration patterns | | Getting Started | Step-by-step tutorial |

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas We Need Help

• 🌐 Translations — Help us reach more developers
• 📖 Documentation — Improve guides and tutorials
• 🧪 Testing — Edge cases and integration tests
• 🔌 Integrations — IDE plugins, browser extensions
• 💡 Ideas — Feature requests and use cases

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs.adverant.ai
• Email: [email protected]

License

MIT License — see LICENSE for details.

Acknowledgments

Built with ❤️ by Adverant

Powered by:

• GraphRAG — Knowledge graph construction
• Claude Code — AI-powered development
• Model Context Protocol — AI tool integration

Stop teaching your AI the same lessons.

Start building institutional intelligence.

Get Started · Star on GitHub