README

Transform your development team into a connected "hive mind" with persistent, intelligent knowledge that remembers everything, learns from usage, and evolves with your decisions.
Inspired by Nolan's Memento—except this time, the graph tattoos actually stick.

🎯 The Problem Memento Solves

Ever stared at your Laravel code and thought, Wait, why did we pick Sanctum over Passport last time? Or watched a new dev waste a day rehashing the same API debate?

Memento fixes the critical problem of institutional knowledge loss in development teams:

🧠 Knowledge Silos: Critical decisions locked in individual developer heads
❓ Context Loss: "Why did we choose this approach?" becomes unanswerable over time
🔄 Repeated Mistakes: Teams rehash the same architectural debates every 6 months
👶 Onboarding Hell: New developers waste weeks rediscovering established patterns
🤖 AI Integration Gap: Current AI tools lack persistent memory of your team's specific context

✨ The Memento Solution: Your Team's "Hive Mind"

Memento creates a persistent, intelligent knowledge graph that serves as your team's collective memory:

🧠 Persistent Team Memory: Every decision, pattern, and lesson learned is permanently stored
🔗 Intelligent Relationships: AI automatically connects related concepts and decisions
📈 Usage-Driven Prioritization: Frequently accessed knowledge rises to the top
⏰ Natural Decay: Unused knowledge gradually fades, keeping the signal strong
🤖 AI-First Design: Built specifically for AI-assisted development workflows

Primary Focus: Development assistance via MCP tools (Cursor AI, VS Code, etc.)
Experimental: App mode for runtime memories (exploring possibilities)

🚧 Beta Release - This package is in beta. While feature-complete and well-tested, we're gathering feedback before the stable v1.0.0 release.

The question isn't whether you need a team memory system—it's whether you can afford to keep losing institutional knowledge every time someone leaves or forgets why a decision was made.

🚀 Quick Start

Installation

# Install beta version
composer require scrypster/memento:^0.9.3-beta

# Set up IDE integration (optional but recommended)
php artisan memento:setup-ide --all

Configuration

# Publish configuration
php artisan vendor:publish --provider="Scrypster\Memento\MementoServiceProvider" --tag="config"

# Set up your .env
MEMENTO_ENABLED=true
MEMENTO_NEO4J_HOST=bolt://localhost:7687
MEMENTO_NEO4J_USERNAME=neo4j
MEMENTO_NEO4J_PASSWORD=your_password
MEMENTO_NEO4J_DATABASE=neo4j

# Dev attribution (optional)
MEMENTO_DEV_NAME=MJ
MEMENTO_DEV_EMAIL=your.email@example.com

MCP Server Setup

Important: After installation, you need to restart your IDE (Cursor AI) to enable MCP tools.

# Check MCP server status
php artisan memento:check-mcp --test-connection --show-tools

# Start MCP server manually (if needed)
php artisan memento:start-mcp --background

Troubleshooting:

If Cursor AI can't see Memento tools, restart Cursor AI
Use php artisan memento:check-mcp to diagnose connection issues
The MCP server should start automatically when Cursor connects

That's It! 🎉

Memento automatically integrates with Laravel Boost and provides MCP tools to any compatible AI tool or IDE. No manual configuration required!

✨ Key Features: The Complete "Hive Mind" Toolkit

🧠 Core Memory Management

🚀 Zero Configuration: Auto-discovers and registers with Laravel Boost
🧠 AI-First Design: Built for MCP-compatible AI tools and IDEs
📝 20+ Memory Operations: Store, search, update, analyze, and discover relationships
🔄 Memory Versioning: Track how decisions evolve over time
📦 Bulk Operations: Efficient batch processing for large datasets

🔍 Advanced Search & Discovery

🔍 Multi-Strategy Search: Full-text, semantic, vector, and graph traversal
🤖 AI-Powered Intelligence: Quality analysis, smart summarization, relationship discovery
📊 Rich Relationships: 13+ relationship types with automatic discovery
🎯 Usage-Driven Prioritization: Frequently accessed knowledge rises to the top
⏰ Natural Decay: Unused knowledge gradually fades, keeping signal strong

⚡ Performance & Scalability

⚡ Production Ready: Optimized for performance and scalability
🗃️ Smart Archiving: Intelligent memory lifecycle management
📈 Advanced Indexing: 20+ specialized Neo4j indexes for optimal performance
💾 Multi-Level Caching: Search results, memory context, and relationship data
🔄 Connection Pooling: Efficient database connection management

🏗️ How the "Hive Mind" Works

Knowledge Graph Architecture

Neo4j Graph Database
├── Nodes (Memories)
│   ├── Decisions: "We use UUIDs for security"
│   ├── Patterns: "Service design patterns"  
│   ├── Solutions: "How we fixed the auth bug"
│   └── People: "Who made what decisions"
└── Relationships (Connections)
    ├── SUPERSEDES: "New decision replaces old"
    ├── IMPLEMENTS: "Code implements decision"
    ├── DEPENDS_ON: "Feature depends on pattern"
    └── USES: "Service uses library"

Dual-Mode Operation

Dev Mode: AI-assisted development decisions (primary use case)
App Mode: Runtime application memories (experimental)

AI-Powered Intelligence

Graphiti Integration: Automatically extracts entities and relationships
Quality Analysis: AI rates memory usefulness and completeness
Smart Summarization: Condenses complex decisions into key insights
Relationship Discovery: Finds hidden connections between concepts

📋 Requirements

PHP: ^8.1 (PHP 8.1 or higher)
Laravel: ^10.0|^11.0|^12.0 (Laravel 10, 11, or 12)
Neo4j: 4.0+ (Neo4j database server)
Composer: For package management

Minimum Setup Cost: $0 (using Neo4j Community + basic features)
Recommended Setup Cost: ~$5-20/month (Neo4j AuraDB + OpenAI API usage)

📖 Detailed Requirements: See Requirements & Setup for complete system requirements, external services, and cost breakdown.

🚀 Quick Start

Installation

# Install beta version
composer require scrypster/memento:^0.9.3-beta

# Or install specific beta version
composer require scrypster/memento:0.9.3-beta

# Or install latest dev version
composer require scrypster/memento:dev-main

# Set up IDE integration (optional but recommended)
php artisan memento:setup-ide --all

Configuration

# Publish configuration
php artisan vendor:publish --provider="Scrypster\Memento\MementoServiceProvider" --tag="config"

# Set up your .env
MEMENTO_ENABLED=true
MEMENTO_NEO4J_HOST=bolt://localhost:7687
MEMENTO_NEO4J_USERNAME=neo4j
MEMENTO_NEO4J_PASSWORD=your_password
MEMENTO_NEO4J_DATABASE=neo4j

# Dev attribution (optional)
MEMENTO_DEV_NAME=MJ  # Your dev handle—falls back to Cursor/Git if blank
MEMENTO_DEV_EMAIL=your.email@example.com  # Optional email for attribution
MEMENTO_DEV_ATTRIBUTION_ENABLED=true
MEMENTO_FALLBACK_TO_CURSOR=true
MEMENTO_FALLBACK_TO_GIT=true

MCP Server Setup

Important: After installation, you need to restart your IDE (Cursor AI) to enable MCP tools.

Check MCP server status:

php artisan memento:check-mcp --test-connection --show-tools

Start MCP server manually (if needed):

php artisan memento:start-mcp --background

Troubleshooting:

If Cursor AI can't see Memento tools, restart Cursor AI
Use php artisan memento:check-mcp to diagnose connection issues
The MCP server should start automatically when Cursor connects

Graphiti AI integration (optional)

MEMENTO_GRAPHITI_ENABLED=true MEMENTO_LLM_PROVIDER=openai MEMENTO_LLM_API_KEY=your_openai_api_key MEMENTO_LLM_MODEL=gpt-4o MEMENTO_LLM_TEMPERATURE=0.1

Dual-mode configuration (optional)

MEMENTO_DEV_DATABASE=memento_dev # Separate dev database MEMENTO_APP_DATABASE=memento_app # Separate app database


### Dual-Mode Support

Memento automatically routes memories based on how they're created:

**MCP Tools (Cursor AI)**: Always use dev mode *(Primary Use Case)*
- Uses `MEMENTO_DEV_NAME` or Git config for attribution
- Stores to `memento_dev` database
- Perfect for capturing build decisions and architectural choices
- Accessed via MCP tools in your IDE

**Application Services**: Always use app mode *(Experimental)*
- Uses Laravel's `auth()->user()` for attribution
- Stores to `memento_app` database
- Exploring possibilities for user-generated content and app-specific memories
- Accessed via `app(AdvancedMemoryService::class)`

No configuration needed - the system automatically chooses the right mode based on the entry point!

### Mode-Specific Configuration

Each mode (`dev` and `app`) can have its own configuration settings:

- **Search Settings**: Different limits, fuzzy matching thresholds
- **Cache Settings**: Different TTL, prefixes, and enabled states  
- **Vector Search**: Different providers, dimensions, and similarity thresholds
- **Connection Settings**: Different databases, hosts, and credentials

This allows you to:
- Use more permissive settings in development (higher limits, fuzzy matching)
- Use stricter settings in production (lower limits, exact matching)
- Have different vector search configurations for dev vs app
- Use separate cache prefixes to avoid conflicts

### That's It! 🎉

Memento automatically integrates with Laravel Boost and provides MCP tools to any compatible AI tool or IDE. No manual configuration required!

### Laravel Compatibility

Memento works with any Laravel application:
- **Laravel 10+** - Full compatibility
- **Laravel 11+** - Optimized for latest features
- **Laravel 12+** - Future-ready architecture
- **Any Laravel app** - Whether it's an API, web app, or console application

## 🧠 Core Features

- **Unified Memory Service**: Single MCP tool with 20+ operations for all memory management
- **AI-Powered Intelligence**: Quality analysis, smart summarization, relationship discovery
- **Advanced Search**: Multi-strategy search with full-text, semantic, vector, and graph traversal
- **Memory Lifecycle**: Validation, archiving, versioning, and smart cleanup
- **Relationship Management**: Rich relationships with automatic discovery and constraints
- **Performance**: Advanced indexing, caching, and query optimization
- **Dual-Mode Operation**: Separate dev and app modes with different configurations

> 📖 **Detailed Features**: See [Core Features](docs/features.md) for comprehensive feature documentation and examples.

## 🧠 Universal Relationship Intelligence System

Advanced AI-powered feature that automatically discovers, suggests, and builds meaningful relationships between any type of information in your knowledge graph.

> 📖 **Relationship Intelligence**: See [Relationship Intelligence](docs/relationship-intelligence/) for complete documentation and setup guides.

## 🛠️ Usage Examples: Building Your Team's "Hive Mind"

### Before Starting Work (Check Collective Knowledge)

Check what the team has already decided

memento search "How do we handle user authentication?" memento search "What are our database design patterns?"

Find related decisions and patterns

memento discover_relationships memory-123 memento decision_timeline "authentication"


### During Development (Document as You Go)

Store decisions as you make them

memento store "We chose Redis for caching because we need sub-millisecond response times"

Connect new work to existing knowledge

memento relate memory-123 memory-456 --type=IMPLEMENTS

Track decision evolution

memento decision_evolution "database architecture"


### After Important Decisions (Share Knowledge)

Analyze decision quality

memento analyze_quality "We use microservices for scalability"

Generate summaries for team sharing

memento smart_summary "Our authentication strategy"

Get complete decision timeline

memento decision_timeline "authentication"


### MCP Tools (Cursor AI) - Natural Language Interface

Store memories naturally

"Store this decision about using UUIDs for security"

Search the collective knowledge

"Find all decisions about authentication" "Show me memories related to database security"

AI-powered analysis

"Analyze the quality of this memory" "Generate a smart summary of this decision" "Discover relationships for this memory"


### PHP Integration (Advanced Usage)

use Scrypster\Memento\Services\AdvancedMemoryService;

// Store a memory $memoryService = app(AdvancedMemoryService::class); $result = $memoryService->storeMemory(

content: "We use UUIDs for all primary keys to ensure security",
type: "decision",
metadata: ['category' => 'security', 'priority' => 'high']

);

// Search the team's collective knowledge $results = $memoryService->searchMemories(

query: "UUID security database",
options: ['type' => 'decision', 'limit' => 10]

);


> 📖 **Complete Usage Guide**: See [Usage Examples](docs/usage.md) for comprehensive examples, API reference, and advanced usage patterns.

## 🎯 Why Memento? The Competitive Advantage

### vs. Traditional Documentation
- **🔍 Searchable**: Full-text and semantic search vs. static docs
- **🔗 Connected**: Relationships between concepts vs. isolated pages
- **🤖 AI-Powered**: Intelligent analysis and discovery vs. manual organization
- **📈 Usage-Driven**: Prioritizes frequently accessed knowledge vs. fixed hierarchy

### vs. Wiki Systems
- **🏗️ Structured**: Enforced data models and relationships vs. free-form text
- **🤖 AI Integration**: Built for AI-assisted development vs. human-only interface
- **🔍 Automatic Discovery**: Finds connections automatically vs. manual linking
- **⏰ Decay System**: Keeps knowledge fresh and relevant vs. static content

### vs. Code Comments
- **💾 Persistent**: Survives code refactoring vs. lost in changes
- **🔍 Searchable**: Find information across entire codebase vs. file-specific
- **📊 Contextual**: Includes business reasoning vs. just technical details
- **🔄 Evolvable**: Tracks how decisions change over time vs. static snapshots

### vs. Slack/Teams
- **🏗️ Structured**: Organized, searchable, and connected vs. message chaos
- **💾 Persistent**: Doesn't get lost in message history vs. buried in threads
- **🤖 AI-Powered**: Intelligent analysis and discovery vs. keyword search
- **🎯 Purpose-Built**: Designed specifically for development knowledge vs. general chat

## 🔧 MCP Tools for AI Development

Memento provides powerful MCP tools that work with Cursor AI, VS Code, and other MCP-compatible IDEs:

- **MemoryService**: 20+ operations for all memory management
- **GraphitiParserTool**: AI-powered text parsing and relationship extraction
- **Natural Language Queries**: "Find all decisions about authentication"
- **AI-Powered Features**: Quality analysis, smart summarization, relationship discovery

### Supported AI Tools & IDEs

- **Cursor** - AI-powered code editor
- **Claude Desktop** - Anthropic's desktop app
- **Continue** - VS Code extension for AI coding
- **Aider** - AI pair programming tool
- **Any MCP-compatible tool** - Through the Model Context Protocol

> 📖 **MCP Tools Guide**: See [MCP Tools](docs/mcp-tools.md) for complete tool documentation and usage examples.

## 📊 Management Commands

Memento provides comprehensive CLI tools for memory management, system maintenance, and IDE integration:

MCP Tools Management

php artisan memento:mcp-tools status php artisan memento:check-mcp --test-connection --show-tools

Memory Operations

php artisan memento:store "Memory content" --type=decision php artisan memento:search "query" --limit=10 php artisan memento:analyze --query="authentication"

System Testing

php artisan neo4j:test-connection php artisan memento:test-dual-mode

IDE Integration

php artisan memento:setup-ide --all


> 📖 **Complete Commands**: See [Management Commands](docs/commands.md) for all available commands and their options.

## ⚙️ Configuration

### Basic Configuration

Core Configuration

MEMENTO_ENABLED=true

Neo4j Configuration

MEMENTO_NEO4J_HOST=bolt://localhost:7687 MEMENTO_NEO4J_USERNAME=neo4j MEMENTO_NEO4J_PASSWORD=your_password MEMENTO_NEO4J_DATABASE=neo4j

AI Configuration (Optional)

MEMENTO_GRAPHITI_ENABLED=true MEMENTO_LLM_PROVIDER=openai MEMENTO_LLM_API_KEY=your_ai_api_key MEMENTO_LLM_MODEL=gpt-4o MEMENTO_LLM_TEMPERATURE=0.1

Dev Attribution (Optional)

MEMENTO_DEV_NAME=MJ MEMENTO_DEV_EMAIL=your.email@example.com


### Supported AI Providers

- **OpenAI**: GPT-4o, GPT-4, GPT-3.5-turbo
- **Anthropic Claude**: Claude-3.5-Sonnet, Claude-3-Haiku
- **Google Gemini**: Gemini-1.5-Flash, Gemini-1.5-Pro
- **Azure OpenAI**: Custom deployment models

> 📖 **Complete Configuration**: See [Configuration Guide](docs/configuration.md) for all environment variables, advanced settings, and AI provider setup.

## 🚀 Performance & Monitoring

- **Advanced Indexing**: 20+ specialized Neo4j indexes for optimal performance
- **Multi-level Caching**: Search results, memory context, and relationship data
- **Query Optimization**: Multi-strategy search with analytics and monitoring
- **Connection Pooling**: Efficient database connection management

> 📖 **Performance Guide**: See [Performance & Monitoring](docs/performance.md) for optimization strategies, caching configuration, and monitoring setup.

## 🔍 Troubleshooting

### Common Issues

- **MCP Tools Not Available**: Restart your IDE and check `php artisan memento:mcp-tools status`
- **Neo4j Connection Issues**: Use `php artisan neo4j:test-connection` to diagnose
- **Vector Search Problems**: Check `php artisan memento:vector status`

> 📖 **Troubleshooting Guide**: See [Troubleshooting](docs/troubleshooting.md) for detailed solutions and debugging steps.

## 📚 Documentation

- **[Requirements & Setup](docs/requirements.md)** - Complete system requirements and setup guide
- **[Core Features](docs/features.md)** - Detailed feature documentation and examples
- **[Usage Examples](docs/usage.md)** - Comprehensive usage patterns and API reference
- **[MCP Tools](docs/mcp-tools.md)** - MCP tools documentation and IDE integration
- **[Configuration Guide](docs/configuration.md)** - All configuration options and AI providers
- **[Management Commands](docs/commands.md)** - Complete CLI commands reference
- **[Performance & Monitoring](docs/performance.md)** - Optimization and monitoring setup
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
- **[Relationship Intelligence](docs/relationship-intelligence/)** - AI-powered relationship discovery
- **[Memory Lifecycle Management](docs/memory-lifecycle.md)** - How memories are created, managed, and removed
- **[Memory Lifecycle Diagrams](docs/memory-lifecycle-diagram.md)** - Visual representations of memory flows
- **[Memento Quick Reference](docs/memento-quick-reference.md)** - Quick reference guide for common operations

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for details.

## 📄 License

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

## 🆘 Support

- **Documentation**: [Full Documentation](docs/)
- **Issues**: [Report Issues](https://bitbucket.org/scrypster/memento/issues)

---

## 🚀 Ready to Build Your Team's "Hive Mind"?

**Memento isn't just another documentation tool—it's a fundamental shift in how development teams manage and share knowledge.**

By creating a persistent, intelligent "hive mind" that learns from usage patterns and evolves with your team's decisions, Memento transforms your Laravel application into a **living knowledge repository** that makes every team member smarter and more efficient.

**The question isn't whether you need a team memory system—it's whether you can afford to keep losing institutional knowledge every time someone leaves or forgets why a decision was made.**

**Memento ensures your team's collective intelligence is preserved, searchable, and continuously evolving.** 🧠✨

---

**Memento** - Remember everything, forget nothing. 🧠✨

*Unlike Leonard Shelby, your memories are here to stay, and they're searchable, versioned, and backed by a knowledge graph that never fades.*

*Built with ❤️ for the Laravel and AI development community.*

scrypster / memento

Maintainers

Details

README

🎯 The Problem Memento Solves

✨ The Memento Solution: Your Team's "Hive Mind"

🚀 Quick Start

Installation

Configuration

MCP Server Setup

That's It! 🎉

✨ Key Features: The Complete "Hive Mind" Toolkit

🧠 Core Memory Management

🔍 Advanced Search & Discovery

⚡ Performance & Scalability

🏗️ How the "Hive Mind" Works

Knowledge Graph Architecture

Dual-Mode Operation

AI-Powered Intelligence

📋 Requirements

🚀 Quick Start

Installation

Configuration

MCP Server Setup

Graphiti AI integration (optional)

Dual-mode configuration (optional)

Check what the team has already decided

Find related decisions and patterns

Store decisions as you make them

Connect new work to existing knowledge

Track decision evolution

Analyze decision quality

Generate summaries for team sharing

Get complete decision timeline

Store memories naturally

Search the collective knowledge

AI-powered analysis

MCP Tools Management

Memory Operations

System Testing

IDE Integration

Core Configuration

Neo4j Configuration

AI Configuration (Optional)

Dev Attribution (Optional)