# Nexus Memory
### Give Your AI Perfect Recall — Across Every Session, Every Project, Forever
[](https://www.npmjs.com/package/@adverant/nexus-memory-skill)
[](https://www.npmjs.com/package/@adverant/nexus-memory-skill)
[](LICENSE)
[](https://claude.ai/code)
[](https://adverant.ai)
[](CONTRIBUTING.md)
**The open-source memory layer for Claude Code that remembers what you learned, why you decided, and how you solved it.**
[Quick Start](#-quick-start) · [Documentation](docs/) · [Use Cases](docs/use-cases.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
---
## 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.
```bash
# 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?
### 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)
```bash
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
```bash
npm install -g @adverant/nexus-memory-skill
```
Then run the installer:
```bash
$(npm root -g)/@adverant/nexus-memory-skill/install.sh
```
### Install via Git
```bash
git clone https://github.com/adverant/nexus-memory-skill.git
cd nexus-memory-skill
./install.sh
```
### Verify Installation
```bash
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
Click to expand step-by-step instructions
1. **Clone the repository**
```bash
git clone https://github.com/adverant/nexus-memory-skill.git
```
2. **Create directories**
```bash
mkdir -p ~/.claude/skills/nexus-memory ~/.claude/hooks
```
3. **Copy skill and hooks**
```bash
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**
```bash
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**
```bash
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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
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](docs/architecture.md) 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
```bash
# 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](https://stedolan.github.io/jq/download/))
- **Claude Code** — With skills support enabled
---
## Use Cases
🐛 Never Solve the Same Bug Twice
Store bug fixes when you solve them:
```bash
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:
```bash
echo '{"query": "Safari date parsing issues"}' | ~/.claude/hooks/recall-memory.sh
```
📐 Architecture Decision Records
Document decisions with context:
```bash
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
```
🔄 Cross-Project Pattern Transfer
Learn a pattern in one project:
```bash
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:
```bash
echo '{"query": "optimistic UI update pattern"}' | ~/.claude/hooks/recall-memory.sh
```
👥 Team Knowledge Sharing
Team members store collective knowledge:
```bash
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.
📂 Repository-Wide Code Understanding
Ingest an entire repository to understand its architecture:
```bash
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:
```bash
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 →](docs/use-cases.md)**
---
## 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 →](ROADMAP.md)**
---
## Documentation
| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | System design, data flow, and component diagrams |
| [Use Cases](docs/use-cases.md) | 20 detailed scenarios with code examples |
| [API Reference](docs/api-reference.md) | Complete API documentation |
| [Integration Guide](docs/integration-guide.md) | Custom integration patterns |
| [Getting Started](docs/getting-started.md) | Step-by-step tutorial |
---
## Contributing
We welcome contributions! See [CONTRIBUTING.md](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](https://github.com/adverant/nexus-memory-skill/issues)
- **Discussions**: [GitHub Discussions](https://github.com/adverant/nexus-memory-skill/discussions)
- **Documentation**: [docs.adverant.ai](https://docs.adverant.ai/nexus/memory)
- **Email**: support@adverant.ai
---
## License
MIT License — see [LICENSE](LICENSE) for details.
---
## Acknowledgments
Built with ❤️ by [Adverant](https://adverant.ai)
Powered by:
- [GraphRAG](https://github.com/microsoft/graphrag) — Knowledge graph construction
- [Claude Code](https://claude.ai/code) — AI-powered development
- [Model Context Protocol](https://modelcontextprotocol.io/) — AI tool integration
---
**Stop teaching your AI the same lessons.**
**Start building institutional intelligence.**
[Get Started](#-quick-start) · [Star on GitHub](https://github.com/adverant/nexus-memory-skill)
