Memento Laravel Package

Getting Started

Minimal Steps

1. Installation Clone the repo and run ./launch.sh (Docker recommended for simplicity).

   git clone https://github.com/scrypster/memento.git
   cd memento
   ./launch.sh
   

   • First run: Downloads Ollama models (~5GB). Subsequent runs are faster.

2. Connect to AI Tool After launch, the script outputs the MCP connection command (e.g., ollama serve memento://localhost:8080). Configure your AI tool (e.g., Ollama, LocalAI) to use this endpoint.

3. First Use Case Start a conversation with your AI tool. Memento automatically:

   • Captures entities (e.g., "John Doe", "Project X").
   • Records relationships (e.g., "John manages Project X").
   • Persists context across sessions in a local Neo4j graph.

   Verify: Query the graph via Memento’s built-in CLI:

   ./memento query "MATCH (n) RETURN n LIMIT 10"
   

Implementation Patterns

Core Workflows

1. AI Integration

   • MCP Protocol: Memento exposes an MCP-compatible endpoint. Use it as a "memory plugin" for any AI tool supporting MCP (e.g., Ollama, LocalAI).
   • Example (Ollama):

     ollama serve memento://localhost:8080 --model llama3
     

   • Laravel Hook: Use Laravel’s process management to auto-restart Memento if it crashes (e.g., via supervisor or laravel-horizon).

2. Graph Querying

   • CLI: Run Cypher queries directly:

     ./memento query "MATCH (a:Person)-[:OWNS]->(p:Project) RETURN a.name, p.name"
     

   • Laravel Integration: Use Guzzle to query the REST API (enabled by default on port 8080):

     $response = Http::post('http://localhost:8080/api/query', [
         'query' => 'MATCH (n) RETURN n LIMIT 5'
     ]);
     $results = $response->json();
     

   • Real-time Updates: Subscribe to graph changes via WebSocket (experimental, see docs/ws.md).

3. Data Ingestion

   • Automatic: Memento passively listens to AI conversations via MCP.
   • Manual: Inject data via the API:

     Http::post('http://localhost:8080/api/ingest', [
         'nodes' => [['label' => 'Person', 'properties' => ['name' => 'Alice']]],
         'relationships' => [['type' => 'OWNS', 'from' => 1, 'to' => 2]]
     ]);
     

4. Contextual Prompting

   • Template Injection: Use Memento’s {{context}} placeholder in prompts to auto-include relevant graph data:

     "You are an assistant with access to my knowledge graph. Here’s what you know so far: {{context}}"
     

   • Laravel Example:

     $prompt = "Analyze the following data: " . $this->getContextFromMemento();
     

Integration Tips

• Docker Compose: Use the provided docker-compose.yml for local development. Mount a volume to persist the Neo4j database:

  volumes:
    - ./data/neo4j:/var/lib/neo4j/data
  

• Model Fine-Tuning: Train your AI model on Memento’s graph exports to improve contextual understanding (export via ./memento export).
• Security: Disable the REST API in production by setting API_ENABLED=false in .env (see docs/security.md).

Gotchas and Tips

Pitfalls

1. Neo4j Performance

   • Issue: Large graphs (>100K nodes) may slow queries.
   • Fix: Use Neo4j’s indexing (configure in neo4j.conf):

     CREATE INDEX FOR (p:Person) ON (p.name);
     

   • Laravel Workaround: Cache frequent queries in Redis:

     $cacheKey = 'memento_query_' . md5($query);
     return Cache::remember($cacheKey, 3600, fn() => Http::post('...')->json());
     

2. MCP Connection Drops

   • Issue: AI tools may disconnect if Memento restarts.
   • Fix: Implement a health check in Laravel (e.g., ping Memento every 5 minutes):

     Http::ping('http://localhost:8080/health');
     

3. Data Duplication

   • Issue: MCP may resend the same context repeatedly.
   • Fix: Use Memento’s deduplicate: true flag in the MCP config (see config/mcp.json).

4. Port Conflicts

   • Issue: Default ports (8080 for API, 7687 for Bolt) may clash.
   • Fix: Override in .env:

     MCP_PORT=9090
     NEO4J_BOLT_PORT=7688
     

Debugging

• Logs: Check logs/memento.log for errors. Enable debug mode:

  ./launch.sh --debug
  

• Graph Inspection: Use Neo4j Browser (accessible at http://localhost:7474) to manually query the graph.
• API Testing: Validate endpoints with:

  curl -X POST http://localhost:8080/api/health
  

Extension Points

1. Custom Node Labels Extend the graph schema by defining new labels in config/schema.json:

   {
     "labels": ["Person", "Project", "CustomLabel"],
     "relationships": ["OWNS", "WORKS_ON", "NEW_RELATION"]
   }
   

   Restart Memento to apply changes.

2. Plugin System Memento supports Go plugins. Example: Add a laravel-sync plugin to auto-push graph changes to a Laravel database:

   // plugins/laravel_sync/plugin.go
   package main
   
   func init() {
       memento.RegisterPlugin(&LaravelSyncPlugin{})
   }
   

   See docs/plugins.md for the interface.

3. Prompt Templates Override default templates in config/prompts/ to customize how context is injected into AI responses.

4. Backup/Restore Use Neo4j’s built-in backup tools to migrate graphs between instances:

   ./memento backup --output ./backup.dump
   ./memento restore --input ./backup.dump