llmemory 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81446e0a05a3028dbcd9bb4745295714304eab3c5b7b898ebd0bb72aa0e48c4e
-  data.tar.gz: 43a8426f108c3c927e72540738fb1b2f946395ad12e01eaba3183e28a38382e4
+  metadata.gz: 2016468aa862476d2bfc4fafef85e340433b0bf940519351a9fb72f3bda5e796
+  data.tar.gz: 31d1d72a3ef8b94b6cef5e696ed29f72357377670d484897350cddcdf17a20ae
 SHA512:
-  metadata.gz: '0396292691b3f8705988d9b86fe33f4f84caee8fcafc498f18631042dff94895175060fd876f6400668effc2e87ae061af60c6bee28c10b69526fab36bfdbdcd'
-  data.tar.gz: 6b7706873ad15231dc70e22c96b89090b9beb36c5fb9b0630e6f5112f125a83e5014964448e37ec59e3e5b248593b55279b2c99f1228218c86f59fd9de8cbec0
+  metadata.gz: f360315f571e5641f53af4006f661a9e432f80280d53a2a7f99d7563f318f23b04950925d2bb2e0716bcad6088b5f929fa15d2b25523f7d83af04b0ac269db3b
+  data.tar.gz: aef3ce481555a0f84630207ff0333fe749d841656dd41c1c6449b4e3797cff73ecd033ce1817ff50d8e87913e783dfed3198eb85ccadfd6683388f9a4e5a8780

data/README.md

@@ -259,6 +259,189 @@ end
 
 The dashboard uses your existing `Llmemory.configuration` (short-term store, long-term store/type, etc.) and does not add any gem dependency; it only runs when Rails is present and you require `llmemory/dashboard`.
 
+## MCP Server (Model Context Protocol)
+
+llmemory includes an MCP server that allows LLM agents (like Claude Code) to interact directly with the memory system. This gives agents "agency" over their own memory—they can search, save, and retrieve memories autonomously.
+
+### Starting the Server
+
+**Stdio mode** (default, for local use with Claude Code):
+
+```bash
+# Via CLI
+llmemory mcp serve
+
+# Or via standalone executable
+llmemory-mcp
+
+# With custom server name
+llmemory mcp serve --name my-memory
+```
+
+**HTTP mode** (for remote access or web integrations):
+
+```bash
+# Start HTTP server on default port 3100
+llmemory mcp serve --http
+
+# Custom port and host
+llmemory mcp serve --http --port 8080 --host 127.0.0.1
+
+# With authentication (recommended for HTTP/HTTPS)
+MCP_TOKEN=your-secret-token llmemory mcp serve --http
+```
+
+**HTTPS mode** (secure remote access):
+
+```bash
+# Start HTTPS server with SSL certificates
+llmemory mcp serve --http --port 443 \
+  --ssl-cert /path/to/cert.pem \
+  --ssl-key /path/to/key.pem
+
+# With authentication (strongly recommended)
+MCP_TOKEN=your-secret-token llmemory mcp serve --http --port 443 \
+  --ssl-cert /path/to/cert.pem \
+  --ssl-key /path/to/key.pem
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Search memories by semantic query |
+| `memory_save` | Save new observations/facts to long-term memory |
+| `memory_retrieve` | Get context optimized for LLM inference (supports timeline context) |
+| `memory_timeline` | Get chronological timeline of recent memories |
+| `memory_timeline_context` | Get N items before/after a specific memory |
+| `memory_add_message` | Add message to short-term conversation |
+| `memory_consolidate` | Extract facts from conversation to long-term |
+| `memory_stats` | Get memory statistics for a user |
+| `memory_info` | Documentation on how to use the tools |
+
+### Configuration for Claude Code
+
+Add to `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llmemory": {
+      "command": "llmemory",
+      "args": ["mcp", "serve"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Or with the standalone executable:
+
+```json
+{
+  "mcpServers": {
+    "llmemory": {
+      "command": "llmemory-mcp"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_TOKEN` | Token for HTTP authentication (if set, requests must include valid token) |
+| `LLMEMORY_DEBUG` | Set to `1` to enable debug output on stderr |
+| `OPENAI_API_KEY` | API key for LLM/embeddings |
+| `REDIS_URL` | Redis URL for short-term store |
+| `DATABASE_URL` | Database URL for persistence |
+
+### HTTP Authentication
+
+When `MCP_TOKEN` is set, the HTTP server requires authentication. Requests must include the token via:
+
+- **Authorization header**: `Authorization: Bearer <token>` or `Authorization: <token>`
+- **Query parameter**: `?token=<token>`
+
+Example with curl:
+
+```bash
+# Using Authorization header
+curl -H "Authorization: Bearer your-secret-token" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  http://localhost:3100/
+
+# Using query parameter
+curl "http://localhost:3100/?token=your-secret-token" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+```
+
+### Recommended Workflow
+
+1. **Start of conversation**: Use `memory_retrieve` to get relevant context
+2. **During conversation**: Use `memory_save` for important observations
+3. **End of conversation**: Use `memory_consolidate` to persist facts
+
+### Timeline Context
+
+The `memory_retrieve` tool supports **timeline context** - showing N events before and after matched memories. This provides situational context around relevant memories:
+
+```json
+{
+  "name": "memory_retrieve",
+  "arguments": {
+    "query": "trabajo",
+    "user_id": "user123",
+    "include_timeline_context": true,
+    "timeline_window": 3
+  }
+}
+```
+
+This returns:
+- Recent conversation (short-term)
+- Relevant memories (long-term)
+- **Timeline context**: 3 events before and after each match
+
+You can also use `memory_timeline_context` directly to explore temporal context around a specific memory:
+
+```json
+{
+  "name": "memory_timeline_context",
+  "arguments": {
+    "user_id": "user123",
+    "item_id": "item_42",
+    "before": 5,
+    "after": 5
+  }
+}
+```
+
+Example output:
+```
+Timeline Context around 'item_42':
+
+BEFORE (3 items):
+  - [2024-01-14] [personal] Usuario vive en Madrid
+  - [2024-01-15] [technical] Usuario programa en Python
+  - [2024-01-16] [preferences] Usuario usa VS Code
+
+TARGET:
+>>> [2024-01-17] [work] Usuario trabaja en Acme Corp
+
+AFTER (3 items):
+  - [2024-01-18] [personal] Usuario tiene un gato
+  - [2024-01-19] [work] Usuario lidera equipo backend
+  - [2024-01-20] [preferences] Usuario prefiere café
+```
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/llmemory-mcp

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__)) unless $LOAD_PATH.include?(File.expand_path("../lib", __dir__))
+
+require "llmemory"
+require "llmemory/mcp"
+
+# Parse minimal arguments
+name = "llmemory"
+ARGV.each_with_index do |arg, i|
+  if arg == "--name" && ARGV[i + 1]
+    name = ARGV[i + 1]
+  elsif arg == "--help" || arg == "-h"
+    puts "Usage: llmemory-mcp [--name NAME]"
+    puts ""
+    puts "Starts an MCP (Model Context Protocol) server for llmemory."
+    puts ""
+    puts "Options:"
+    puts "  --name NAME    Server name (default: llmemory)"
+    puts "  --help, -h     Show this help"
+    puts ""
+    puts "Environment variables:"
+    puts "  LLMEMORY_DEBUG    Set to 1 to enable debug output on stderr"
+    puts ""
+    puts "Example configuration for Claude Code (~/.claude/claude_code_config.json):"
+    puts '  {'
+    puts '    "mcpServers": {'
+    puts '      "llmemory": {'
+    puts '        "command": "llmemory-mcp"'
+    puts '      }'
+    puts '    }'
+    puts '  }'
+    exit 0
+  end
+end
+
+# Silence stderr for clean protocol unless debugging
+unless ENV["LLMEMORY_DEBUG"]
+  $stderr.reopen(File::NULL, "w")
+end
+
+server = Llmemory::MCP::Server.new(name: name)
+server.run_stdio

data/lib/llmemory/cli/commands/mcp.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Mcp < Base
+        def option_parser(parser)
+          @server_name = "llmemory"
+          @http_mode = false
+          @port = 3100
+          @host = "0.0.0.0"
+          @ssl_cert = nil
+          @ssl_key = nil
+
+          parser.banner = "Usage: llmemory mcp [serve] [options]"
+          parser.on("--name NAME", "Server name (default: llmemory)") { |v| @server_name = v }
+          parser.on("--http", "Run as HTTP server instead of stdio") { @http_mode = true }
+          parser.on("--port PORT", Integer, "HTTP port (default: 3100)") { |v| @port = v }
+          parser.on("--host HOST", "HTTP host (default: 0.0.0.0)") { |v| @host = v }
+          parser.on("--ssl-cert FILE", "SSL certificate file for HTTPS") { |v| @ssl_cert = v }
+          parser.on("--ssl-key FILE", "SSL private key file for HTTPS") { |v| @ssl_key = v }
+          parser.on("-h", "--help", "Show this help") do
+            puts parser
+            exit
+          end
+        end
+
+        def execute(argv, _opts)
+          action = argv.shift || "serve"
+
+          case action
+          when "serve"
+            run_server
+          when "help", "--help", "-h"
+            show_help
+          else
+            $stderr.puts "Unknown MCP action: #{action}"
+            $stderr.puts "Usage: llmemory mcp [serve] [options]"
+            exit 1
+          end
+        end
+
+        private
+
+        def show_help
+          puts "Usage: llmemory mcp [serve] [options]"
+          puts ""
+          puts "Options:"
+          puts "  --name NAME      Server name (default: llmemory)"
+          puts "  --http           Run as HTTP server instead of stdio"
+          puts "  --port PORT      HTTP port (default: 3100)"
+          puts "  --host HOST      HTTP host (default: 0.0.0.0)"
+          puts "  --ssl-cert FILE  SSL certificate file for HTTPS"
+          puts "  --ssl-key FILE   SSL private key file for HTTPS"
+          puts ""
+          puts "Environment Variables:"
+          puts "  MCP_TOKEN      If set, enables token authentication for HTTP mode"
+          puts "  LLMEMORY_DEBUG Set to 1 to enable debug output"
+          puts ""
+          puts "Authentication (HTTP/HTTPS mode only):"
+          puts "  When MCP_TOKEN is set, requests must include either:"
+          puts "  - Authorization header: 'Bearer <token>' or '<token>'"
+          puts "  - Query parameter: '?token=<token>'"
+          puts ""
+          puts "Starts an MCP (Model Context Protocol) server that exposes llmemory"
+          puts "tools for use with LLM agents like Claude Code."
+          puts ""
+          puts "Example configuration for Claude Code (~/.claude/claude_code_config.json):"
+          puts '  {'
+          puts '    "mcpServers": {'
+          puts '      "llmemory": {'
+          puts '        "command": "llmemory",'
+          puts '        "args": ["mcp", "serve"]'
+          puts '      }'
+          puts '    }'
+          puts '  }'
+          puts ""
+          puts "HTTP mode example:"
+          puts "  MCP_TOKEN=secret123 llmemory mcp serve --http --port 3100"
+          puts ""
+          puts "HTTPS mode example:"
+          puts "  MCP_TOKEN=secret123 llmemory mcp serve --http --port 443 \\"
+          puts "    --ssl-cert /path/to/cert.pem --ssl-key /path/to/key.pem"
+        end
+
+        def run_server
+          require_relative "../../mcp"
+
+          server = Llmemory::MCP::Server.new(name: @server_name)
+
+          if @http_mode
+            validate_ssl_options!
+            server.run_http(port: @port, host: @host, ssl_cert: @ssl_cert, ssl_key: @ssl_key)
+          else
+            # Silence stderr to avoid interference with MCP protocol
+            # unless debugging is enabled
+            unless ENV["LLMEMORY_DEBUG"]
+              $stderr.reopen(File::NULL, "w")
+            end
+
+            server.run_stdio
+          end
+        end
+
+        def validate_ssl_options!
+          # If one SSL option is provided, both must be provided
+          if (@ssl_cert && !@ssl_key) || (!@ssl_cert && @ssl_key)
+            $stderr.puts "Error: Both --ssl-cert and --ssl-key must be provided for HTTPS"
+            exit 1
+          end
+
+          # Validate files exist if SSL is enabled
+          if @ssl_cert && @ssl_key
+            unless File.exist?(@ssl_cert)
+              $stderr.puts "Error: SSL certificate file not found: #{@ssl_cert}"
+              exit 1
+            end
+            unless File.exist?(@ssl_key)
+              $stderr.puts "Error: SSL key file not found: #{@ssl_key}"
+              exit 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli.rb

@@ -7,6 +7,7 @@ require_relative "cli/commands/short_term"
 require_relative "cli/commands/long_term"
 require_relative "cli/commands/stats"
 require_relative "cli/commands/search"
+require_relative "cli/commands/mcp"
 
 module Llmemory
   class CLI
@@ -47,7 +48,8 @@ module Llmemory
         "edges" => Cli::Commands::LongTerm::Edges,
         "graph" => Cli::Commands::LongTerm::Graph,
         "search" => Cli::Commands::Search,
-        "stats" => Cli::Commands::Stats
+        "stats" => Cli::Commands::Stats,
+        "mcp" => Cli::Commands::Mcp
       }[normalized]
     end
 
@@ -68,6 +70,7 @@ module Llmemory
           graph USER_ID            Export graph (--format dot|json)
           search USER_ID "query"   Search in memory
           stats [USER_ID]          Show statistics
+          mcp [serve]              Start MCP server for LLM agents
 
         Run 'llmemory <command> --help' for command-specific options.
       HELP

data/lib/llmemory/long_term/file_based/storages/active_record_storage.rb

@@ -138,8 +138,40 @@ module Llmemory
             LlmemoryItem.where(user_id: user_id).count
           end
 
+          def get_items_around(user_id, reference, before: 5, after: 5)
+            items = get_all_items(user_id)
+            find_around(items, reference, before, after)
+          end
+
+          def get_resources_around(user_id, reference, before: 5, after: 5)
+            resources = get_all_resources(user_id)
+            find_around(resources, reference, before, after)
+          end
+
           private
 
+          def find_around(items, reference, before, after)
+            return { before: [], target: nil, after: [] } if items.empty?
+
+            idx = if reference.is_a?(String) && reference.match?(/^\d{4}-/)
+              target_time = Time.parse(reference)
+              items.index { |i| i[:created_at] >= target_time } || items.size
+            else
+              items.index { |i| i[:id] == reference }
+            end
+
+            return { before: [], target: nil, after: [] } unless idx
+
+            start_idx = [idx - before, 0].max
+            end_idx = [idx + after, items.size - 1].min
+
+            {
+              before: items[start_idx...idx] || [],
+              target: items[idx],
+              after: items[(idx + 1)..end_idx] || []
+            }
+          end
+
           def sanitize_like(str)
             (str || "").to_s.gsub(/[%_\\]/) { |c| "\\#{c}" }
           end

data/lib/llmemory/long_term/file_based/storages/base.rb

@@ -80,6 +80,14 @@ module Llmemory
           def count_items(user_id:)
             raise NotImplementedError, "#{self.class}#count_items must be implemented"
           end
+
+          def get_items_around(user_id, reference, before: 5, after: 5)
+            raise NotImplementedError, "#{self.class}#get_items_around must be implemented"
+          end
+
+          def get_resources_around(user_id, reference, before: 5, after: 5)
+            raise NotImplementedError, "#{self.class}#get_resources_around must be implemented"
+          end
         end
       end
     end

data/lib/llmemory/long_term/file_based/storages/database_storage.rb

@@ -197,8 +197,42 @@ module Llmemory
             result.first["c"].to_i
           end
 
+          def get_items_around(user_id, reference, before: 5, after: 5)
+            ensure_tables!
+            items = get_all_items(user_id)
+            find_around(items, reference, before, after)
+          end
+
+          def get_resources_around(user_id, reference, before: 5, after: 5)
+            ensure_tables!
+            resources = get_all_resources(user_id)
+            find_around(resources, reference, before, after)
+          end
+
           private
 
+          def find_around(items, reference, before, after)
+            return { before: [], target: nil, after: [] } if items.empty?
+
+            idx = if reference.is_a?(String) && reference.match?(/^\d{4}-/)
+              target_time = Time.parse(reference)
+              items.index { |i| i[:created_at] >= target_time } || items.size
+            else
+              items.index { |i| i[:id] == reference }
+            end
+
+            return { before: [], target: nil, after: [] } unless idx
+
+            start_idx = [idx - before, 0].max
+            end_idx = [idx + after, items.size - 1].min
+
+            {
+              before: items[start_idx...idx] || [],
+              target: items[idx],
+              after: items[(idx + 1)..end_idx] || []
+            }
+          end
+
           def conn
             @connection ||= begin
               require "pg"

data/lib/llmemory/long_term/file_based/storages/memory_storage.rb

@@ -116,6 +116,42 @@ module Llmemory
           def count_items(user_id:)
             @items[user_id].size
           end
+
+          def get_items_around(user_id, reference, before: 5, after: 5)
+            items = @items[user_id].sort_by { |i| i[:created_at] }
+            find_around(items, reference, :id, before, after)
+          end
+
+          def get_resources_around(user_id, reference, before: 5, after: 5)
+            resources = @resources[user_id].sort_by { |r| r[:created_at] }
+            find_around(resources, reference, :id, before, after)
+          end
+
+          private
+
+          def find_around(items, reference, id_key, before, after)
+            return { before: [], target: nil, after: [] } if items.empty?
+
+            idx = if reference.is_a?(String) && reference.match?(/^\d{4}-/)
+              # ISO timestamp - find closest item at or after this time
+              target_time = Time.parse(reference)
+              items.index { |i| i[:created_at] >= target_time } || items.size
+            else
+              # Item ID
+              items.index { |i| i[id_key] == reference }
+            end
+
+            return { before: [], target: nil, after: [] } unless idx
+
+            start_idx = [idx - before, 0].max
+            end_idx = [idx + after, items.size - 1].min
+
+            {
+              before: items[start_idx...idx] || [],
+              target: items[idx],
+              after: items[(idx + 1)..end_idx] || []
+            }
+          end
         end
       end
     end

data/lib/llmemory/long_term/graph_based/storages/active_record_storage.rb

@@ -123,6 +123,32 @@ module Llmemory
             LlmemoryGraphEdge.where(user_id: user_id, archived_at: nil).count
           end
 
+          def get_edges_around(user_id, reference, before: 5, after: 5)
+            edges = LlmemoryGraphEdge.where(user_id: user_id, archived_at: nil)
+              .order(:created_at)
+              .map { |r| record_to_edge(r) }
+
+            return { before: [], target: nil, after: [] } if edges.empty?
+
+            idx = if reference.is_a?(String) && reference.match?(/^\d{4}-/)
+              target_time = Time.parse(reference)
+              edges.index { |e| e.created_at >= target_time } || edges.size
+            else
+              edges.index { |e| e.id == reference || e.id.to_s == reference.to_s }
+            end
+
+            return { before: [], target: nil, after: [] } unless idx
+
+            start_idx = [idx - before, 0].max
+            end_idx = [idx + after, edges.size - 1].min
+
+            {
+              before: edges[start_idx...idx] || [],
+              target: edges[idx],
+              after: edges[(idx + 1)..end_idx] || []
+            }
+          end
+
           private
 
           def record_to_node(r)

data/lib/llmemory/long_term/graph_based/storages/base.rb

@@ -48,6 +48,10 @@ module Llmemory
           def count_edges(user_id)
             raise NotImplementedError, "#{self.class}#count_edges must be implemented"
           end
+
+          def get_edges_around(user_id, reference, before: 5, after: 5)
+            raise NotImplementedError, "#{self.class}#get_edges_around must be implemented"
+          end
         end
       end
     end

data/lib/llmemory/long_term/graph_based/storages/memory_storage.rb

@@ -118,6 +118,29 @@ module Llmemory
           def count_edges(user_id)
             @edges[user_id].count { |e| !e.archived? }
           end
+
+          def get_edges_around(user_id, reference, before: 5, after: 5)
+            edges = @edges[user_id].reject(&:archived?).sort_by(&:created_at)
+            return { before: [], target: nil, after: [] } if edges.empty?
+
+            idx = if reference.is_a?(String) && reference.match?(/^\d{4}-/)
+              target_time = Time.parse(reference)
+              edges.index { |e| e.created_at >= target_time } || edges.size
+            else
+              edges.index { |e| e.id == reference }
+            end
+
+            return { before: [], target: nil, after: [] } unless idx
+
+            start_idx = [idx - before, 0].max
+            end_idx = [idx + after, edges.size - 1].min
+
+            {
+              before: edges[start_idx...idx] || [],
+              target: edges[idx],
+              after: edges[(idx + 1)..end_idx] || []
+            }
+          end
         end
       end
     end