htm 0.0.10 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b552d9b1e6a197c35d1ff2c64d4c8eb94a36a0e67d05efe1c10d305cf8f23d78
-  data.tar.gz: 58fa199e1a3af9fb9c3a9e8fc0fe9ee779209a44baecbccdfdf6f570f5e7c692
+  metadata.gz: c6e41109b86fd5c51c8f96cec8a11ea9455035da54d72ae461b3b2f0a7ab7a8d
+  data.tar.gz: 1fe15917933aefa827a12c6e92406711ab95449097cb78bdab4c0f6510f595c1
 SHA512:
-  metadata.gz: 9326f318f1677ea5cad5e5f6cdda4125421a13bde13d1c7bef0a2b2e8096873a7762f11d008c8d0e64365f90272aad58699b39a3af40f0c188f7e961eef6d2df
-  data.tar.gz: 6f25fa0089349b0872db11427747e525ab46a9528d1ada22be183be260bad40d48ef692f78d922ba0803b817f2f661fa143721bf180882f34c575f4650e65448
+  metadata.gz: c02e326797a6986e1a5b987bec948f09c0ffc7cb45045898e3fc6faf5c57c9bf3ca4d399324e88528f994c7e3e1989bb71f462aae8adbb270b7c99654aa135d3
+  data.tar.gz: 4ee90ea84f36ab2d85c72cae4f5a1382e9a174d354f2d976d73b8915cb5dc8df68f6ae799ec082076293ce9b386500b94b4fe12d291903c0804351f5fd027151

data/.claude/settings.local.json

@@ -84,7 +84,10 @@
       "WebFetch(domain:www.barndominiumlife.com)",
       "Bash(git rm:*)",
       "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" psql -c \"DROP TABLE IF EXISTS working_memories CASCADE;\" htm_development)",
-      "Bash(git checkout:*)"
+      "Bash(git checkout:*)",
+      "WebFetch(domain:rubygems.org)",
+      "WebFetch(domain:www.rubyllm-mcp.com)",
+      "Bash(gem contents:*)"
     ],
     "deny": [],
     "ask": []

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.11] - 2025-12-02
+
+### Added
+- **MCP Server and Client** - Model Context Protocol integration for AI assistants
+  - `bin/htm_mcp.rb` - FastMCP-based server exposing HTM tools:
+    - `SetRobotTool` - Set robot identity for the session (per-client isolation)
+    - `GetRobotTool` - Get current robot information
+    - `GetWorkingMemoryTool` - Retrieve working memory for session restore
+    - `RememberTool` - Store information with tags and metadata
+    - `RecallTool` - Search memories with vector/fulltext/hybrid strategies
+    - `ForgetTool` / `RestoreTool` - Soft delete and restore memories
+    - `ListTagsTool` - List tags with optional prefix filtering
+    - `StatsTool` - Memory usage statistics
+  - Resources: `htm://statistics`, `htm://tags/hierarchy`, `htm://memories/recent`
+  - STDERR logging to avoid corrupting MCP JSON-RPC protocol
+  - Session-based robot identity via `MCPSession` module
+  - `examples/mcp_client.rb` - Interactive chat client using ruby_llm-mcp:
+    - Prompts for robot name on startup (or uses `HTM_ROBOT_NAME` env var)
+    - Session restore: offers to restore working memory from previous session
+    - Interactive chat loop with Ollama LLM (gpt-oss model)
+    - Tool call logging for visibility
+    - Slash commands: `/tools`, `/resources`, `/stats`, `/tags`, `/clear`, `/help`, `/exit`
+- **Session restore feature** - MCP client can restore previous session context
+  - `GetWorkingMemoryTool` returns all nodes in working memory for a robot
+  - Client prompts user to restore previous session on startup
+  - Working memory injected into chat context for continuity
+
+### Fixed
+- **GetWorkingMemoryTool** now uses `joins(:node)` to exclude soft-deleted nodes
+- **StatsTool** fixed scope error (`Node.active` → `Node.count` with default_scope)
+- **MCP tool response parsing** - Extract `.text` from `RubyLLM::MCP::Content` objects
+
 ## [0.0.10] - 2025-12-02
 
 ### Added
@@ -436,7 +468,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Working memory size is user-configurable
 - See ADRs for detailed architectural decisions and rationale
 
-[Unreleased]: https://github.com/madbomber/htm/compare/v0.0.10...HEAD
+[Unreleased]: https://github.com/madbomber/htm/compare/v0.0.12...HEAD
+[0.0.12]: https://github.com/madbomber/htm/compare/v0.0.10...v0.0.12
 [0.0.10]: https://github.com/madbomber/htm/compare/v0.0.9...v0.0.10
 [0.0.9]: https://github.com/madbomber/htm/compare/v0.0.8...v0.0.9
 [0.0.8]: https://github.com/madbomber/htm/compare/v0.0.7...v0.0.8

data/README.md

@@ -1400,13 +1400,13 @@ This separation allows you to provide any LLM implementation while HTM handles r
 ## Roadmap
 
 - [x] Phase 1: Foundation (basic two-tier memory)
-- [ ] Phase 2: RAG retrieval (semantic search)
-- [ ] Phase 3: Relationships & tags
-- [ ] Phase 4: Working memory management
-- [ ] Phase 5: Hive mind features
-- [ ] Phase 6: Operations & observability
-- [ ] Phase 7: Advanced features
-- [ ] Phase 8: Production-ready gem
+- [x] Phase 2: RAG retrieval (semantic search)
+- [x] Phase 3: Relationships & tags
+- [x] Phase 4: Working memory management
+- [x] Phase 5: Hive mind features
+- [x] Phase 6: Operations & observability
+- [x] Phase 7: Advanced features
+- [x] Phase 8: Production-ready gem
 
 
 ## Contributing

data/bin/htm_mcp.rb

@@ -0,0 +1,527 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# htm/bin/htm_mcp.rb
+
+# MCP Server Example for HTM
+#
+# This example demonstrates using FastMCP to expose HTM's memory
+# capabilities as an MCP (Model Context Protocol) server that can
+# be used by AI assistants like Claude Desktop.
+#
+# Prerequisites:
+# 1. Install fast-mcp gem: gem install fast-mcp
+# 2. Set HTM_DBURL environment variable
+# 3. Initialize database schema: rake db_setup
+#
+# Usage:
+#   ruby examples/mcp_server.rb
+#
+# The server uses STDIO transport by default, making it compatible
+# with Claude Desktop and other MCP clients.
+#
+# Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):
+#   {
+#     "mcpServers": {
+#       "htm-memory": {
+#         "command": "ruby",
+#         "args": ["/path/to/htm/examples/mcp_server.rb"],
+#         "env": {
+#           "HTM_DBURL": "postgresql://postgres@localhost:5432/htm_development"
+#         }
+#       }
+#     }
+#   }
+
+require_relative '../lib/htm'
+
+begin
+  require 'fast_mcp'
+rescue LoadError
+  warn "Error: fast-mcp gem not found."
+  warn "Install it with: gem install fast-mcp"
+  exit 1
+end
+
+# Check environment
+unless ENV['HTM_DBURL']
+  warn "Error: HTM_DBURL not set."
+  warn "  export HTM_DBURL=\"postgresql://postgres@localhost:5432/htm_development\""
+  exit 1
+end
+
+# IMPORTANT: MCP uses STDIO for JSON-RPC communication.
+# ALL logging must go to STDERR to avoid corrupting the protocol.
+# Create a logger that writes to STDERR for MCP server diagnostics.
+MCP_STDERR_LOG = Logger.new($stderr)
+MCP_STDERR_LOG.level = Logger::INFO
+MCP_STDERR_LOG.formatter = proc do |severity, datetime, _progname, msg|
+  "[MCP #{severity}] #{datetime.strftime('%H:%M:%S')} #{msg}\n"
+end
+
+# Silent logger for RubyLLM/HTM internals (prevents STDOUT corruption)
+mcp_logger = Logger.new(IO::NULL)
+
+# Configure RubyLLM to not log to STDOUT (corrupts MCP protocol)
+require 'ruby_llm'
+RubyLLM.configure do |config|
+  config.logger = mcp_logger
+end
+
+# Configure HTM
+HTM.configure do |config|
+  config.job_backend = :inline  # Synchronous for MCP responses
+  config.logger = mcp_logger    # Silent logging for MCP
+end
+
+# Session state for the current robot
+# Each MCP client spawns its own server process, so this is naturally isolated
+module MCPSession
+  DEFAULT_ROBOT_NAME = "mcp_default"
+
+  class << self
+    def htm_instance
+      @htm_instance ||= HTM.new(robot_name: DEFAULT_ROBOT_NAME)
+    end
+
+    def set_robot(name)
+      @robot_name   = name
+      @htm_instance = HTM.new(robot_name: name)
+      MCP_STDERR_LOG.info "Robot set: #{name} (id=#{@htm_instance.robot_id})"
+      @htm_instance
+    end
+
+    def robot_name
+      @robot_name || DEFAULT_ROBOT_NAME
+    end
+
+    def robot_initialized?
+      @robot_name != nil
+    end
+  end
+end
+
+# Tool: Set the robot identity for this session
+class SetRobotTool < FastMcp::Tool
+  description "Set the robot identity for this session. Call this first to establish your robot name."
+
+  arguments do
+    required(:name).filled(:string).description("The robot name (will be created if it doesn't exist)")
+  end
+
+  def call(name:)
+    MCP_STDERR_LOG.info "SetRobotTool called: name=#{name.inspect}"
+
+    htm   = MCPSession.set_robot(name)
+    robot = HTM::Models::Robot.find(htm.robot_id)
+
+    {
+      success:    true,
+      robot_id:   htm.robot_id,
+      robot_name: htm.robot_name,
+      node_count: robot.node_count,
+      message:    "Robot '#{name}' is now active for this session"
+    }.to_json
+  end
+end
+
+# Tool: Get current robot info
+class GetRobotTool < FastMcp::Tool
+  description "Get information about the current robot for this session"
+
+  arguments do
+  end
+
+  def call
+    MCP_STDERR_LOG.info "GetRobotTool called"
+
+    htm   = MCPSession.htm_instance
+    robot = HTM::Models::Robot.find(htm.robot_id)
+
+    {
+      success:        true,
+      robot_id:       htm.robot_id,
+      robot_name:     htm.robot_name,
+      initialized:    MCPSession.robot_initialized?,
+      memory_summary: robot.memory_summary
+    }.to_json
+  end
+end
+
+# Tool: Get working memory contents for session restore
+class GetWorkingMemoryTool < FastMcp::Tool
+  description "Get all working memory contents for the current robot. Use this to restore a previous session."
+
+  arguments do
+  end
+
+  def call
+    htm = MCPSession.htm_instance
+    robot = HTM::Models::Robot.find(htm.robot_id)
+    MCP_STDERR_LOG.info "GetWorkingMemoryTool called for robot=#{htm.robot_name}"
+
+    # Get all nodes in working memory with their metadata
+    # Filter out any robot_nodes where the node has been deleted (node uses default_scope)
+    working_memory_nodes = robot.robot_nodes
+                                .in_working_memory
+                                .joins(:node)  # Inner join excludes deleted nodes
+                                .includes(node: :tags)
+                                .order(last_remembered_at: :desc)
+                                .filter_map do |rn|
+      next unless rn.node  # Extra safety check
+
+      {
+        id: rn.node.id,
+        content:            rn.node.content,
+        tags:               rn.node.tags.map(&:name),
+        remember_count:     rn.remember_count,
+        last_remembered_at: rn.last_remembered_at&.iso8601,
+        created_at:         rn.node.created_at.iso8601
+      }
+    end
+
+    MCP_STDERR_LOG.info "GetWorkingMemoryTool complete: #{working_memory_nodes.length} nodes in working memory"
+
+    {
+      success:        true,
+      robot_id:       htm.robot_id,
+      robot_name:     htm.robot_name,
+      count:          working_memory_nodes.length,
+      working_memory: working_memory_nodes
+    }.to_json
+  rescue StandardError => e
+    MCP_STDERR_LOG.error "GetWorkingMemoryTool error: #{e.message}"
+    { success: false, error: e.message, count: 0, working_memory: [] }.to_json
+  end
+end
+
+# Tool: Remember information
+class RememberTool < FastMcp::Tool
+  description "Store information in HTM long-term memory with optional tags"
+
+  arguments do
+    required(:content).filled(:string).description("The content to remember")
+    optional(:tags).array(:string).description("Optional tags for categorization (e.g., ['database:postgresql', 'config'])")
+    optional(:metadata).hash.description("Optional metadata key-value pairs")
+  end
+
+  def call(content:, tags: [], metadata: {})
+    MCP_STDERR_LOG.info "RememberTool called: content=#{content[0..50].inspect}..."
+
+    htm = MCPSession.htm_instance
+    node_id = htm.remember(content, tags: tags, metadata: metadata)
+    node = HTM::Models::Node.includes(:tags).find(node_id)
+
+    MCP_STDERR_LOG.info "Memory stored: node_id=#{node_id}, robot=#{htm.robot_name}, tags=#{node.tags.map(&:name)}"
+
+    {
+      success:        true,
+      node_id:        node_id,
+      robot_id:       htm.robot_id,
+      robot_name:     htm.robot_name,
+      content:        node.content,
+      tags:           node.tags.map(&:name),
+      created_at:     node.created_at.iso8601
+    }.to_json
+  end
+end
+
+# Tool: Recall memories
+class RecallTool < FastMcp::Tool
+  description "Search and retrieve memories from HTM using semantic, full-text, or hybrid search"
+
+  arguments do
+    required(:query).filled(:string).description("Search query - can be natural language or keywords")
+    optional(:limit).filled(:integer).description("Maximum number of results (default: 10)")
+    optional(:strategy).filled(:string).description("Search strategy: 'vector', 'fulltext', or 'hybrid' (default: 'hybrid')")
+    optional(:timeframe).filled(:string).description("Filter by time: 'today', 'this week', 'this month', or ISO8601 date range")
+  end
+
+  def call(query:, limit: 10, strategy: 'hybrid', timeframe: nil)
+    htm = MCPSession.htm_instance
+    MCP_STDERR_LOG.info "RecallTool called: query=#{query.inspect}, strategy=#{strategy}, limit=#{limit}, robot=#{htm.robot_name}"
+
+    recall_opts = {
+      limit: limit,
+      strategy: strategy.to_sym,
+      raw: true
+    }
+
+    # Parse timeframe if provided
+    if timeframe
+      recall_opts[:timeframe] = parse_timeframe(timeframe)
+    end
+
+    memories = htm.recall(query, **recall_opts)
+
+    results = memories.map do |memory|
+      node = HTM::Models::Node.includes(:tags).find(memory['id'])
+      {
+        id:         memory['id'],
+        content:    memory['content'],
+        tags:       node.tags.map(&:name),
+        created_at: memory['created_at'],
+        score:      memory['combined_score'] || memory['similarity']
+      }
+    end
+
+    MCP_STDERR_LOG.info "Recall complete: found #{results.length} memories"
+
+    {
+      success:    true,
+      query:      query,
+      strategy:   strategy,
+      robot_name: htm.robot_name,
+      count:      results.length,
+      results:    results
+    }.to_json
+  end
+
+  private
+
+  def parse_timeframe(timeframe)
+    case timeframe.downcase
+    when 'today'
+      Time.now.beginning_of_day..Time.now
+    when 'this week'
+      1.week.ago..Time.now
+    when 'this month'
+      1.month.ago..Time.now
+    else
+      # Try to parse as ISO8601 range (start..end)
+      if timeframe.include?('..')
+        parts = timeframe.split('..')
+        Time.parse(parts[0])..Time.parse(parts[1])
+      else
+        # Single date - from that date to now
+        Time.parse(timeframe)..Time.now
+      end
+    end
+  rescue ArgumentError
+    nil  # Invalid timeframe, skip filtering
+  end
+end
+
+# Tool: Forget a memory
+class ForgetTool < FastMcp::Tool
+  description "Soft-delete a memory from HTM (can be restored later)"
+
+  arguments do
+    required(:node_id).filled(:integer).description("The ID of the node to forget")
+  end
+
+  def call(node_id:)
+    htm = MCPSession.htm_instance
+    MCP_STDERR_LOG.info "ForgetTool called: node_id=#{node_id}, robot=#{htm.robot_name}"
+
+    htm.forget(node_id)
+
+    MCP_STDERR_LOG.info "Memory soft-deleted: node_id=#{node_id}"
+
+    {
+      success:    true,
+      node_id:    node_id,
+      robot_name: htm.robot_name,
+      message:    "Memory soft-deleted. Use restore to recover."
+    }.to_json
+  rescue ActiveRecord::RecordNotFound
+    MCP_STDERR_LOG.warn "ForgetTool failed: node #{node_id} not found"
+    {
+      success: false,
+      error: "Node #{node_id} not found"
+    }.to_json
+  end
+end
+
+# Tool: Restore a forgotten memory
+class RestoreTool < FastMcp::Tool
+  description "Restore a soft-deleted memory"
+
+  arguments do
+    required(:node_id).filled(:integer).description("The ID of the node to restore")
+  end
+
+  def call(node_id:)
+    htm = MCPSession.htm_instance
+    MCP_STDERR_LOG.info "RestoreTool called: node_id=#{node_id}, robot=#{htm.robot_name}"
+
+    htm.restore(node_id)
+
+    MCP_STDERR_LOG.info "Memory restored: node_id=#{node_id}"
+
+    {
+      success:    true,
+      node_id:    node_id,
+      robot_name: htm.robot_name,
+      message:    "Memory restored successfully"
+    }.to_json
+  rescue ActiveRecord::RecordNotFound
+    MCP_STDERR_LOG.warn "RestoreTool failed: node #{node_id} not found"
+    {
+      success: false,
+      error: "Node #{node_id} not found"
+    }.to_json
+  end
+end
+
+# Tool: List tags
+class ListTagsTool < FastMcp::Tool
+  description "List all tags in HTM, optionally filtered by prefix"
+
+  arguments do
+    optional(:prefix).filled(:string).description("Filter tags by prefix (e.g., 'database' returns 'database:postgresql', etc.)")
+  end
+
+  def call(prefix: nil)
+    MCP_STDERR_LOG.info "ListTagsTool called: prefix=#{prefix.inspect}"
+
+    tags_query = HTM::Models::Tag.order(:name)
+    tags_query = tags_query.where("name LIKE ?", "#{prefix}%") if prefix
+
+    tags = tags_query.map do |tag|
+      {
+        name: tag.name,
+        node_count: tag.nodes.count
+      }
+    end
+
+    MCP_STDERR_LOG.info "ListTagsTool complete: found #{tags.length} tags"
+
+    {
+      success: true,
+      prefix: prefix,
+      count: tags.length,
+      tags: tags
+    }.to_json
+  end
+end
+
+# Tool: Get memory statistics
+class StatsTool < FastMcp::Tool
+  description "Get statistics about HTM memory usage"
+
+  arguments do
+  end
+
+  def call
+    htm = MCPSession.htm_instance
+    robot = HTM::Models::Robot.find(htm.robot_id)
+    MCP_STDERR_LOG.info "StatsTool called for robot=#{htm.robot_name}"
+
+    # Note: Node uses default_scope to exclude deleted, so .count returns active nodes
+    total_nodes           = HTM::Models::Node.count
+    deleted_nodes         = HTM::Models::Node.deleted.count
+    nodes_with_embeddings = HTM::Models::Node.with_embeddings.count
+    nodes_with_tags       = HTM::Models::Node.joins(:tags).distinct.count
+    total_tags            = HTM::Models::Tag.count
+    total_robots          = HTM::Models::Robot.count
+
+    MCP_STDERR_LOG.info "StatsTool complete: #{total_nodes} active nodes, #{total_tags} tags"
+
+    {
+      success:       true,
+      current_robot: {
+        name:           htm.robot_name,
+        id:             htm.robot_id,
+        memory_summary: robot.memory_summary
+      },
+      statistics: {
+        nodes: {
+          active:          total_nodes,
+          deleted:         deleted_nodes,
+          with_embeddings: nodes_with_embeddings,
+          with_tags:       nodes_with_tags
+        },
+        tags: {
+          total: total_tags
+        },
+        robots: {
+          total: total_robots
+        }
+      }
+    }.to_json
+  rescue StandardError => e
+    MCP_STDERR_LOG.error "StatsTool error: #{e.message}"
+    { success: false, error: e.message }.to_json
+  end
+end
+
+# Resource: Memory Statistics
+class MemoryStatsResource < FastMcp::Resource
+  uri "htm://statistics"
+  resource_name "HTM Memory Statistics"
+  mime_type "application/json"
+
+  def content
+    htm = MCPSession.htm_instance
+    {
+      total_nodes:        HTM::Models::Node.active.count,
+      total_tags:         HTM::Models::Tag.count,
+      total_robots:       HTM::Models::Robot.count,
+      current_robot:      htm.robot_name,
+      robot_id:           htm.robot_id,
+      robot_initialized:  MCPSession.robot_initialized?,
+      embedding_provider: HTM.configuration.embedding_provider,
+      embedding_model:    HTM.configuration.embedding_model
+    }.to_json
+  end
+end
+
+# Resource: Tag Hierarchy
+class TagHierarchyResource < FastMcp::Resource
+  uri "htm://tags/hierarchy"
+  resource_name "HTM Tag Hierarchy"
+  mime_type "text/plain"
+
+  def content
+    HTM::Models::Tag.all.tree_string
+  end
+end
+
+# Resource: Recent Memories
+class RecentMemoriesResource < FastMcp::Resource
+  uri           "htm://memories/recent"
+  resource_name "Recent HTM Memories"
+  mime_type     "application/json"
+
+  def content
+    recent = HTM::Models::Node.active
+                              .includes(:tags)
+                              .order(created_at: :desc)
+                              .limit(20)
+                              .map do |node|
+      {
+        id:         node.id,
+        content:    node.content[0..200],
+        tags:       node.tags.map(&:name),
+        created_at: node.created_at.iso8601
+      }
+    end
+
+    { recent_memories: recent }.to_json
+  end
+end
+
+# Create and configure the MCP server
+server = FastMcp::Server.new(
+  name:    'htm-memory-server',
+  version: HTM::VERSION
+)
+
+# Register tools
+server.register_tool(SetRobotTool)    # Call first to set robot identity
+server.register_tool(GetRobotTool)    # Get current robot info
+server.register_tool(GetWorkingMemoryTool)  # Get working memory for session restore
+server.register_tool(RememberTool)
+server.register_tool(RecallTool)
+server.register_tool(ForgetTool)
+server.register_tool(RestoreTool)
+server.register_tool(ListTagsTool)
+server.register_tool(StatsTool)
+
+# Register resources
+server.register_resource(MemoryStatsResource)
+server.register_resource(TagHierarchyResource)
+server.register_resource(RecentMemoriesResource)
+
+# Start the server (STDIO transport by default)
+server.start

data/examples/README.md

@@ -107,6 +107,127 @@ ruby examples/timeframe_demo.rb
 
 ---
 
+### mcp_server.rb & mcp_client.rb
+
+**Model Context Protocol (MCP) integration for AI assistants.**
+
+A pair of examples demonstrating how to expose HTM as an MCP server and connect to it from a chat client. This enables AI assistants like Claude Desktop to use HTM's memory capabilities.
+
+#### mcp_server.rb
+
+An MCP server that exposes HTM's memory operations as tools:
+
+```bash
+ruby examples/mcp_server.rb
+```
+
+**Tools exposed:**
+- `SetRobotTool` - Set the robot identity for this session (call first)
+- `GetRobotTool` - Get current robot information
+- `GetWorkingMemoryTool` - Get working memory contents for session restore
+- `RememberTool` - Store information with optional tags and metadata
+- `RecallTool` - Search memories using vector, fulltext, or hybrid strategies
+- `ForgetTool` - Soft-delete a memory (recoverable)
+- `RestoreTool` - Restore a soft-deleted memory
+- `ListTagsTool` - List tags with optional prefix filtering
+- `StatsTool` - Get memory usage statistics
+
+**Resources exposed:**
+- `htm://statistics` - Memory statistics as JSON
+- `htm://tags/hierarchy` - Tag hierarchy as text tree
+- `htm://memories/recent` - Last 20 memories
+
+**Claude Desktop configuration** (`~/.config/claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "htm-memory": {
+      "command": "ruby",
+      "args": ["/path/to/htm/examples/mcp_server.rb"],
+      "env": {
+        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+      }
+    }
+  }
+}
+```
+
+#### mcp_client.rb
+
+An interactive chat client that connects to the MCP server via STDIO and uses a local Ollama model (gpt-oss) for conversation:
+
+```bash
+ruby examples/mcp_client.rb
+```
+
+**Features:**
+- Prompts for robot name on startup (or uses `HTM_ROBOT_NAME` env var)
+- Calls `SetRobotTool` to establish robot identity with the server
+- Offers to restore previous session from working memory
+- Connects to `mcp_server.rb` automatically via STDIO transport
+- Interactive chat loop with tool calling
+- LLM decides when to remember/recall information
+- Logs tool calls and results for visibility
+
+**Commands:**
+- `/tools` - List available MCP tools
+- `/resources` - List available MCP resources
+- `/clear` - Clear chat history
+- `/help` - Show help
+- `/exit` - Quit
+
+**Example startup and conversation:**
+```
+$ ruby examples/mcp_client.rb
+Connecting to HTM MCP server...
+[✓] Connected to HTM MCP server
+[✓] Found 9 tools:
+    - SetRobotTool: Set the robot identity for this session...
+    - GetRobotTool: Get information about the current robot...
+    - GetWorkingMemoryTool: Get all working memory contents...
+    ...
+
+Enter your robot name (or press Enter for default): alice-assistant
+[✓] Robot name: alice-assistant
+Setting robot identity on MCP server...
+[✓] Robot identity set: alice-assistant (id=5, nodes=12)
+
+Found 3 memories in working memory from previous session.
+Restore previous session? (y/N): y
+[✓] Will restore 3 memories after chat setup
+
+Initializing chat with gpt-oss:latest...
+[✓] Chat initialized with tools attached
+Restoring 3 memories to chat context...
+[✓] Restored 3 memories to chat context
+
+======================================================================
+HTM MCP Client - AI Chat with Memory Tools
+======================================================================
+
+Robot: alice-assistant
+Model: gpt-oss:latest (via Ollama)
+...
+
+you> What's the API rate limit?
+
+assistant> The API rate limit is 1000 requests per minute.
+```
+
+**Additional dependencies:**
+```bash
+gem install fast-mcp ruby_llm-mcp
+ollama pull gpt-oss  # Or your preferred model
+```
+
+**Environment Variables:**
+- `HTM_DBURL` - PostgreSQL connection (required)
+- `OLLAMA_URL` - Ollama server URL (default: http://localhost:11434)
+- `OLLAMA_MODEL` - Model to use (default: gpt-oss:latest)
+- `HTM_ROBOT_NAME` - Robot name (optional, prompts if not set)
+
+---
+
 ## Application Examples
 
 ### example_app/
@@ -245,6 +366,8 @@ examples/
 ├── custom_llm_configuration.rb    # LLM integration patterns
 ├── file_loader_usage.rb           # Document loading
 ├── timeframe_demo.rb              # Time-based filtering
+├── mcp_server.rb                  # MCP server exposing HTM tools
+├── mcp_client.rb                  # MCP client with chat interface
 ├── example_app/
 │   ├── app.rb                     # Full-featured demo app
 │   └── Rakefile
@@ -274,6 +397,8 @@ examples/
 | Custom LLM integration | `custom_llm_configuration.rb` |
 | Loading documents/files | `file_loader_usage.rb` |
 | Time-based queries | `timeframe_demo.rb` |
+| MCP server for AI assistants | `mcp_server.rb` |
+| MCP client with chat interface | `mcp_client.rb` |
 | Web application | `sinatra_app/` |
 | CLI tool | `cli_app/` |
 | Multi-robot coordination | `robot_groups/` |

data/examples/mcp_client.rb

@@ -0,0 +1,529 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP Client Example for HTM
+#
+# This example demonstrates using ruby_llm-mcp to connect to the
+# HTM MCP server and interact with it through a chat interface
+# using a local Ollama model.
+#
+# Prerequisites:
+# 1. Install gems: gem install ruby_llm-mcp
+# 2. Have Ollama running with gpt-oss model: ollama pull gpt-oss
+# 3. Set HTM_DBURL environment variable
+# 4. The htm_mcp.rb must be available (this client will launch it)
+#
+# Usage:
+#   ruby examples/mcp_client.rb
+#
+# The client connects to the HTM MCP server via STDIO transport
+# and provides an interactive chat loop where you can:
+# - Ask the LLM to remember information
+# - Query memories using natural language
+# - List tags and statistics
+# - All through conversational AI with tool calling
+
+require 'ruby_llm'
+require 'ruby_llm/mcp'
+
+# Configuration
+OLLAMA_MODEL    = ENV.fetch('OLLAMA_MODEL', 'gpt-oss:latest')
+OLLAMA_URL      = ENV.fetch('OLLAMA_URL', 'http://localhost:11434')
+MCP_SERVER_PATH = File.expand_path('../bin/htm_mcp.rb', __dir__)
+ENV_ROBOT_NAME  = ENV['HTM_ROBOT_NAME']  # nil if not set, allows prompting
+
+class HTMMcpClient
+  attr_reader :robot_name
+
+  def initialize
+    validate_environment
+    setup_ruby_llm
+    setup_mcp_client
+    prompt_for_robot_name
+    set_robot_identity
+    check_working_memory
+    setup_chat
+    restore_session_if_requested
+  end
+
+
+  def run
+    print_banner
+    chat_loop
+  ensure
+    cleanup
+  end
+
+  private
+
+  def validate_environment
+    unless ENV['HTM_DBURL']
+      warn 'Error: HTM_DBURL not set.'
+      warn '  export HTM_DBURL="postgresql://postgres@localhost:5432/htm_development"'
+      exit 1
+    end
+
+    unless File.exist?(MCP_SERVER_PATH)
+      warn "Error: MCP server not found at #{MCP_SERVER_PATH}"
+      warn 'Please ensure mcp_server.rb exists in the examples directory.'
+      exit 1
+    end
+
+    # Check Ollama is running
+    require 'net/http'
+    begin
+      uri = URI(OLLAMA_URL)
+      Net::HTTP.get_response(uri)
+    rescue StandardError => e
+      warn "Error: Cannot connect to Ollama at #{OLLAMA_URL}"
+      warn "  #{e.message}"
+      warn 'Please ensure Ollama is running: ollama serve'
+      exit 1
+    end
+  end
+
+
+  def setup_ruby_llm
+    # Configure RubyLLM for Ollama
+    RubyLLM.configure do |config|
+      ollama_api_base = OLLAMA_URL.end_with?('/v1') ? OLLAMA_URL : "#{OLLAMA_URL}/v1"
+      config.ollama_api_base = ollama_api_base
+    end
+  end
+
+
+  def setup_mcp_client
+    puts 'Connecting to HTM MCP server...'
+
+    @mcp_client = RubyLLM::MCP.client(
+      name: 'htm-memory',
+      transport_type: :stdio,
+      request_timeout: 60_000, # 60 seconds (in ms) for Ollama embedding generation
+      config: {
+        command: RbConfig.ruby,
+        args: [MCP_SERVER_PATH],
+        env: {
+          'HTM_DBURL' => ENV['HTM_DBURL'],
+          'OLLAMA_URL' => OLLAMA_URL
+        }
+      }
+    )
+
+    # Wait for server to be ready
+    sleep 0.5
+
+    if @mcp_client.alive?
+      puts '[✓] Connected to HTM MCP server'
+    else
+      warn '[✗] Failed to connect to HTM MCP server'
+      exit 1
+    end
+
+    # List available tools
+    @tools = @mcp_client.tools
+    puts "[✓] Found #{@tools.length} tools:"
+    @tools.each do |tool|
+      puts "    - #{tool.name}: #{tool.description[0..60]}..."
+    end
+    puts
+  end
+
+
+  def prompt_for_robot_name
+    if ENV_ROBOT_NAME
+      @robot_name = ENV_ROBOT_NAME
+      puts "[✓] Using robot name from HTM_ROBOT_NAME: #{@robot_name}"
+      return
+    end
+
+    puts
+    print 'Enter your robot name (or press Enter for "Assistant"): '
+    input = gets&.chomp
+
+    @robot_name = if input.nil? || input.empty?
+                    'Assistant'
+                  else
+                    input
+                  end
+
+    puts "[✓] Robot name: #{@robot_name}"
+  end
+
+
+  def set_robot_identity
+    puts 'Setting robot identity on MCP server...'
+
+    # Find the SetRobotTool
+    set_robot_tool = @tools.find { |t| t.name == 'SetRobotTool' }
+
+    unless set_robot_tool
+      warn '[⚠] SetRobotTool not found - using default robot identity'
+      return
+    end
+
+    # Call SetRobotTool directly via MCP
+    result = set_robot_tool.call(name: @robot_name)
+
+    # Parse the result
+    begin
+      response = JSON.parse(result.is_a?(String) ? result : result.to_s)
+      if response['success']
+        puts "[✓] Robot identity set: #{response['robot_name']} (id=#{response['robot_id']}, nodes=#{response['node_count']})"
+      else
+        warn "[⚠] Failed to set robot identity: #{response['error']}"
+      end
+    rescue JSON::ParserError => e
+      warn "[⚠] Could not parse SetRobotTool response: #{e.message}"
+    end
+    puts
+  end
+
+
+  def check_working_memory
+    # Check if there's working memory to restore
+    get_wm_tool = @tools.find { |t| t.name == 'GetWorkingMemoryTool' }
+    @working_memory_to_restore = nil
+    return unless get_wm_tool
+
+    result = get_wm_tool.call({})
+
+    # Extract JSON from MCP Content object
+    json_str = result.respond_to?(:text) ? result.text : result.to_s
+    response = JSON.parse(json_str)
+
+    # Debug: show what we got
+    puts "[Debug] Working memory check: success=#{response['success']}, count=#{response['count']}"
+
+    return unless response['success'] && response['count'].to_i > 0
+
+    puts "Found #{response['count']} memories in working memory from previous session."
+    print 'Restore previous session? (y/N): '
+    input = gets&.chomp&.downcase
+
+    if %w[y yes].include?(input)
+      @working_memory_to_restore = response['working_memory']
+      puts "[✓] Will restore #{@working_memory_to_restore.length} memories after chat setup"
+    else
+      puts '[✓] Starting fresh session'
+    end
+    puts
+  rescue JSON::ParserError => e
+    warn "[⚠] Could not parse working memory response: #{e.message}"
+    warn "[⚠] Raw: #{json_str.inspect[0..200]}" if defined?(json_str)
+  rescue StandardError => e
+    warn "[⚠] Error checking working memory: #{e.class} - #{e.message}"
+  end
+
+
+  def restore_session_if_requested
+    return unless @working_memory_to_restore
+
+    puts "Restoring #{@working_memory_to_restore.length} memories to chat context..."
+
+    # Build a system context from the working memory
+    context_parts = @working_memory_to_restore.map do |mem|
+      tags_str = mem['tags'].empty? ? '' : " [#{mem['tags'].join(', ')}]"
+      "- #{mem['content']}#{tags_str}"
+    end
+
+    context_message = <<~CONTEXT
+      The following information was remembered from your previous session with this user:
+
+      #{context_parts.join("\n")}
+
+      Use this context to inform your responses, but don't explicitly mention that you're restoring a session unless asked.
+    CONTEXT
+
+    # Add the context as a system message to prime the chat
+    @chat.add_message(role: :user, content: "Previous session context: #{context_message}")
+    @chat.add_message(role: :assistant,
+                      content: "I've restored context from our previous session. How can I help you today?")
+
+    puts "[✓] Restored #{@working_memory_to_restore.length} memories to chat context"
+    puts
+  end
+
+
+  def setup_chat
+    puts "Initializing chat with #{OLLAMA_MODEL}..."
+
+    @chat = RubyLLM.chat(
+      model: OLLAMA_MODEL,
+      provider: :ollama,
+      assume_model_exists: true
+    )
+
+    # Attach MCP tools to the chat
+    @chat.with_tools(*@tools)
+
+    # Set up tool call logging
+    setup_tool_callbacks
+
+    puts '[✓] Chat initialized with tools attached'
+  end
+
+
+  def print_banner
+    puts
+    puts '=' * 70
+    puts 'HTM MCP Client - AI Chat with Memory Tools'
+    puts '=' * 70
+    puts
+    puts "Robot: #{@robot_name}"
+    puts "Model: #{OLLAMA_MODEL} (via Ollama)"
+    puts "MCP Server: #{MCP_SERVER_PATH}"
+    puts
+    puts 'Available tools:'
+    @tools.each do |tool|
+      puts "  • #{tool.name}"
+    end
+    puts
+    puts 'Example queries:'
+    puts '  "Remember that the API rate limit is 1000 requests per minute"'
+    puts '  "What do you know about databases?"'
+    puts '  "Show me the memory statistics"'
+    puts '  "List all tags"'
+    puts '  "Forget node 123"'
+    puts
+    puts 'Commands:'
+    puts '  /tools     - List available MCP tools'
+    puts '  /resources - List available MCP resources'
+    puts '  /stats     - Show memory statistics'
+    puts '  /tags      - List all tags'
+    puts '  /clear     - Clear chat history'
+    puts '  /help      - Show this help'
+    puts '  /exit      - Quit'
+    puts
+    puts '=' * 70
+    puts
+  end
+
+
+  def chat_loop
+    loop do
+      print 'you> '
+      input = gets&.chomp
+      break if input.nil?
+
+      next if input.empty?
+
+      # Handle commands
+      case input
+      when '/exit', '/quit', '/q'
+        break
+      when '/tools'
+        show_tools
+        next
+      when '/resources'
+        show_resources
+        next
+      when '/stats'
+        show_stats
+        next
+      when '/tags'
+        show_tags
+        next
+      when '/clear'
+        clear_chat
+        next
+      when '/help'
+        print_banner
+        next
+      end
+
+      # Send to LLM with tools
+      begin
+        print "\n#{@robot_name}> "
+        response = @chat.ask(input)
+        puts response.content
+        puts
+      rescue StandardError => e
+        puts "\n[✗] Error: #{e.message}"
+        puts "    #{e.class}: #{e.backtrace.first}"
+        puts
+      end
+    end
+
+    puts "\nGoodbye!"
+  end
+
+
+  def show_tools
+    puts "\nAvailable MCP Tools:"
+    puts '-' * 50
+    @tools.each do |tool|
+      puts
+      puts "#{tool.name}"
+      puts "  #{tool.description}"
+    end
+    puts
+  end
+
+
+  def show_resources
+    puts "\nAvailable MCP Resources:"
+    puts '-' * 50
+    begin
+      resources = @mcp_client.resources
+      if resources.empty?
+        puts '  (no resources available)'
+      else
+        resources.each do |resource|
+          puts
+          puts "#{resource.uri}"
+          puts "  #{resource.name}" if resource.respond_to?(:name)
+        end
+      end
+    rescue StandardError => e
+      puts "  Error fetching resources: #{e.message}"
+    end
+    puts
+  end
+
+
+  def show_stats
+    puts "\nMemory Statistics:"
+    puts '-' * 50
+
+    stats_tool = @tools.find { |t| t.name == 'StatsTool' }
+    unless stats_tool
+      puts '  StatsTool not available'
+      puts
+      return
+    end
+
+    result = stats_tool.call({})
+
+    # Handle different response types from MCP
+    # RubyLLM::MCP::Content objects have a .text attribute
+    json_str = case result
+               when String then result
+               when Hash then result.to_json
+               else
+                 # Try to extract text from MCP Content objects
+                 if result.respond_to?(:text)
+                   result.text
+                 elsif result.respond_to?(:content)
+                   result.content.is_a?(String) ? result.content : result.content.to_s
+                 else
+                   result.to_s
+                 end
+               end
+
+    response = JSON.parse(json_str)
+
+    if response['success']
+      robot = response['current_robot']
+      stats = response['statistics']
+
+      puts
+      puts "Current Robot: #{robot['name']} (id=#{robot['id']})"
+      puts "  Working memory: #{robot['memory_summary']['in_working_memory']} nodes"
+      puts "  Total nodes: #{robot['memory_summary']['total_nodes']}"
+      puts "  With embeddings: #{robot['memory_summary']['with_embeddings']}"
+      puts
+      puts 'Global Statistics:'
+      puts "  Active nodes: #{stats['nodes']['active']}"
+      puts "  Deleted nodes: #{stats['nodes']['deleted']}"
+      puts "  Total tags: #{stats['tags']['total']}"
+      puts "  Total robots: #{stats['robots']['total']}"
+    else
+      puts "  Error: #{response['error']}"
+    end
+    puts
+  rescue JSON::ParserError => e
+    puts "  Error parsing response: #{e.message}"
+    puts "  Raw response: #{result.inspect[0..200]}"
+    puts
+  rescue StandardError => e
+    puts "  Error: #{e.message}"
+    puts
+  end
+
+
+  def show_tags
+    puts "\nTags:"
+    puts '-' * 50
+
+    tags_tool = @tools.find { |t| t.name == 'ListTagsTool' }
+    unless tags_tool
+      puts '  ListTagsTool not available'
+      puts
+      return
+    end
+
+    result = tags_tool.call({})
+
+    # Extract JSON from MCP Content object
+    json_str = result.respond_to?(:text) ? result.text : result.to_s
+    response = JSON.parse(json_str)
+
+    if response['success']
+      tags = response['tags']
+      if tags.empty?
+        puts '  (no tags found)'
+      else
+        tags.each do |tag|
+          puts "  #{tag['name']} (#{tag['node_count']} nodes)"
+        end
+      end
+    else
+      puts "  Error: #{response['error']}"
+    end
+    puts
+  rescue JSON::ParserError => e
+    puts "  Error parsing response: #{e.message}"
+    puts
+  rescue StandardError => e
+    puts "  Error: #{e.message}"
+    puts
+  end
+
+
+  def clear_chat
+    @chat = RubyLLM.chat(
+      model: OLLAMA_MODEL,
+      provider: :ollama,
+      assume_model_exists: true
+    )
+    @chat.with_tools(*@tools)
+    setup_tool_callbacks
+
+    puts '[✓] Chat history cleared'
+    puts
+  end
+
+
+  def setup_tool_callbacks
+    @chat.on_tool_call do |tool_call|
+      puts "\n[Tool Call] #{tool_call.name}"
+      puts "  Arguments: #{tool_call.arguments.inspect}"
+    end
+
+    @chat.on_tool_result do |tool_call, result|
+      # tool_call may be a Content object, so safely get the name
+      tool_name = tool_call.respond_to?(:name) ? tool_call.name : tool_call.class.name.split('::').last
+      puts "[Tool Result] #{tool_name}"
+      display_result = result.to_s
+      display_result = display_result[0..200] + '...' if display_result.length > 200
+      puts "  Result: #{display_result}"
+      puts
+    end
+  end
+
+
+  def cleanup
+    @mcp_client&.close if @mcp_client.respond_to?(:close)
+  end
+end
+
+# Main entry point
+begin
+  require 'ruby_llm/mcp'
+rescue LoadError
+  warn 'Error: ruby_llm-mcp gem not found.'
+  warn 'Install it with: gem install ruby_llm-mcp'
+  exit 1
+end
+
+HTMMcpClient.new.run

data/lib/htm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HTM
-  VERSION = "0.0.10"
+  VERSION = "0.0.11"
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: htm
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
 platform: ruby
 authors:
 - Dewayne VanHoozer
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -121,6 +121,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +191,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -213,7 +241,8 @@ description: |
   (Retrieval-Augmented Generation) techniques.
 email:
 - dvanhoozer@gmail.com
-executables: []
+executables:
+- htm_mcp.rb
 extensions: []
 extra_rdoc_files: []
 files:
@@ -249,6 +278,7 @@ files:
 - README.md
 - Rakefile
 - SETUP.md
+- bin/htm_mcp.rb
 - config/database.yml
 - db/migrate/00001_enable_extensions.rb
 - db/migrate/00002_create_robots.rb
@@ -402,6 +432,7 @@ files:
 - examples/example_app/Rakefile
 - examples/example_app/app.rb
 - examples/file_loader_usage.rb
+- examples/mcp_client.rb
 - examples/robot_groups/lib/robot_group.rb
 - examples/robot_groups/lib/working_memory_channel.rb
 - examples/robot_groups/multi_process.rb