personality 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8995b66c26162fbdbb780899f5e8e1f97fe3bdf890e587297bb41058c1f3c0f
-  data.tar.gz: 326558e3feb47e8b95000b8db597d3a0fd677d7a2d04f7ae9b18353559819ae8
+  metadata.gz: 6d10c8c7ae61bc430f61154cdc2760ece25c3868a70b3eafd1405830679ca348
+  data.tar.gz: 788487ea2930b59b020c8aee337ad8b1eea4448ff43ded86d23c4c82616871c6
 SHA512:
-  metadata.gz: 4ab0e534ca8179f15f9c824a3ea08b1d52db29291323749c2d3797b4467eef818758d7202eaacd51b8988ecff47c74531abe581f4304fa1ed5935eecb1db91bd
-  data.tar.gz: cac3b00f2335b80f737ab3c3e08c26d0c640d196261bc680f818843819c5fedb6df964a922e2aa1bf56923d385ef52538b02dda4a6815bf0300e7412965894ac
+  metadata.gz: c6c572c470a06ef00997edc63a2987aecc40864d480ccad7577b431659634d43e365bda551906a2c43c759491757e751735e5e3baedfd874c78fad592eb9a446
+  data.tar.gz: 35949f8a0ebaea35733f45b66fb6f2eb90ea6a9c74bbf8da3dd101ddaa3f633b314a900d47be30b63f2c8b29a02d9306775930238c781c8750d5ea2ffb757a87

data/exe/psn-tts

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "personality"
+require "personality/mcp/tts_server"
+
+Personality::MCP::TtsServer.run

data/lib/personality/cart_manager.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "zip" unless defined?(Zip)
+require "yaml"
+require "fileutils"
+
+module Personality
+  # Identity configuration from preferences
+  IdentityConfig = Struct.new(:agent, :name, :full_name, :version, :type, :source, :tagline, keyword_init: true) do
+    def self.from_hash(h)
+      h ||= {}
+      new(
+        agent: h["agent"].to_s,
+        name: h["name"].to_s,
+        full_name: h["full_name"].to_s,
+        version: h["version"].to_s,
+        type: h["type"].to_s,
+        source: h["source"].to_s,
+        tagline: h["tagline"].to_s
+      )
+    end
+
+    def to_hash
+      members.each_with_object({}) { |k, h|
+        v = self[k]
+        h[k.to_s] = v unless v.nil? || v.empty?
+      }
+    end
+  end
+
+  # TTS configuration
+  TTSConfig = Struct.new(:enabled, :voice, keyword_init: true) do
+    def self.from_hash(h)
+      h ||= {}
+      new(enabled: h.fetch("enabled", true), voice: h.fetch("voice", "").to_s)
+    end
+
+    def to_hash
+      {"enabled" => enabled, "voice" => voice}
+    end
+  end
+
+  # Preferences config (identity + tts + extras)
+  PreferencesConfig = Struct.new(:identity, :tts, :extra, keyword_init: true) do
+    def self.from_hash(data)
+      data ||= {}
+      known = %w[identity tts]
+      extra = data.except(*known)
+      new(
+        identity: IdentityConfig.from_hash(data["identity"]),
+        tts: TTSConfig.from_hash(data["tts"]),
+        extra: extra
+      )
+    end
+
+    def to_hash
+      h = {}
+      id_h = identity.to_hash
+      h["identity"] = id_h unless id_h.empty?
+      h["tts"] = tts.to_hash if tts.enabled || !tts.voice.empty?
+      h.merge(extra || {})
+    end
+  end
+
+  # A loaded cartridge
+  Cartridge = Struct.new(:path, :tag, :version, :memories, :preferences, :created_at, keyword_init: true) do
+    def name
+      n = preferences&.identity&.name
+      (n.nil? || n.empty?) ? tag : n
+    end
+
+    def voice
+      preferences&.tts&.voice
+    end
+
+    def memory_count
+      memories&.size || 0
+    end
+  end
+
+  # Manages .pcart (personality cartridge) ZIP files.
+  #
+  # A .pcart file is a ZIP archive containing:
+  #   persona.yml      - tag, version, and memories array
+  #   preferences.yml  - identity metadata and TTS settings
+  #
+  class CartManager
+    EXTENSION = ".pcart"
+
+    def initialize(carts_dir: nil, training_dir: nil)
+      @carts_dir = carts_dir || File.join(Dir.home, ".local", "share", "personality", "carts")
+      @training_dir = training_dir
+    end
+
+    attr_reader :carts_dir, :training_dir
+
+    # Load a cartridge from a .pcart file.
+    #
+    # @param path [String] Path to the .pcart file
+    # @return [Cartridge]
+    def load_cart(path)
+      raise Errno::ENOENT, "Cart file not found: #{path}" unless File.exist?(path)
+
+      require "zip"
+      Zip::File.open(path) do |zf|
+        # persona.yml is required
+        persona_entry = zf.find_entry("persona.yml")
+        raise ArgumentError, "Missing persona.yml in cart" unless persona_entry
+
+        persona_data = YAML.safe_load(persona_entry.get_input_stream.read, permitted_classes: [Date, Time]) || {}
+
+        tag = persona_data.fetch("tag", File.basename(path, EXTENSION))
+        version = persona_data.fetch("version", "").to_s
+
+        memories = parse_memories(persona_data.fetch("memories", []))
+
+        # preferences.yml is optional
+        prefs_data = {}
+        prefs_entry = zf.find_entry("preferences.yml")
+        if prefs_entry
+          prefs_data = YAML.safe_load(prefs_entry.get_input_stream.read, permitted_classes: [Date, Time]) || {}
+        end
+
+        # Also check persona.yml for embedded preferences (training format)
+        if persona_data.key?("preferences")
+          base_prefs = persona_data["preferences"]
+          base_prefs.each { |k, v| prefs_data[k] = v unless prefs_data.key?(k) } if base_prefs.is_a?(Hash)
+        end
+
+        preferences = PreferencesConfig.from_hash(prefs_data)
+
+        Cartridge.new(
+          path: path,
+          tag: tag,
+          version: version,
+          memories: memories,
+          preferences: preferences
+        )
+      end
+    end
+
+    # Save a cartridge to a .pcart file.
+    #
+    # @param cart [Cartridge] The cartridge to save
+    # @param path [String, nil] Output path (defaults to carts_dir/tag.pcart)
+    # @return [String] Path to the saved file
+    def save_cart(cart, path: nil)
+      path ||= begin
+        FileUtils.mkdir_p(@carts_dir)
+        File.join(@carts_dir, "#{cart.tag}#{EXTENSION}")
+      end
+
+      FileUtils.mkdir_p(File.dirname(path))
+
+      persona_yaml = YAML.dump({
+        "tag" => cart.tag,
+        "version" => cart.version,
+        "memories" => cart.memories.map { |m| {"subject" => m.subject, "content" => m.content} }
+      })
+
+      prefs_yaml = YAML.dump(cart.preferences.to_hash)
+
+      require "zip"
+      Zip::OutputStream.open(path) do |zos|
+        zos.put_next_entry("persona.yml")
+        zos.write(persona_yaml)
+        zos.put_next_entry("preferences.yml")
+        zos.write(prefs_yaml)
+      end
+
+      path
+    end
+
+    # Create a cartridge from a training YAML file.
+    #
+    # @param training_path [String] Path to the training file
+    # @param output_path [String, nil] Output path for the .pcart file
+    # @return [Cartridge]
+    def create_from_training(training_path, output_path: nil)
+      require_relative "training_parser"
+
+      parser = TrainingParser.new
+      doc = parser.parse_file(training_path)
+
+      tag = doc.tag.empty? ? File.basename(training_path, ".*").downcase : doc.tag
+      preferences = PreferencesConfig.from_hash(doc.preferences)
+
+      cart = Cartridge.new(
+        path: nil,
+        tag: tag,
+        version: doc.version,
+        memories: doc.memories,
+        preferences: preferences,
+        created_at: Time.now.utc.to_s
+      )
+
+      saved_path = save_cart(cart, path: output_path)
+      cart.path = saved_path
+      cart
+    end
+
+    # Import a cart's memories into the database.
+    #
+    # @param cart [Cartridge] The cartridge to import
+    # @return [Hash] Import result with counts
+    def import_memories(cart)
+      require_relative "db"
+      require_relative "cart"
+      require_relative "memory"
+
+      DB.migrate!
+
+      # Ensure cart exists in DB with full identity
+      db_cart = Cart.create(
+        cart.tag,
+        name: cart.preferences.identity.name,
+        type: cart.preferences.identity.type,
+        tagline: cart.preferences.identity.tagline
+      )
+
+      # Update fields that create doesn't set
+      db = DB.connection
+      db.execute(
+        "UPDATE carts SET version = ?, source = ?, name = COALESCE(NULLIF(?, ''), name), type = COALESCE(NULLIF(?, ''), type), tagline = COALESCE(NULLIF(?, ''), tagline) WHERE id = ?",
+        [cart.version, cart.preferences.identity.source, cart.preferences.identity.name, cart.preferences.identity.type, cart.preferences.identity.tagline, db_cart[:id]]
+      )
+
+      mem = Memory.new
+      stored = 0
+      skipped = 0
+
+      cart.memories.each do |training_mem|
+        # Check for existing memory with same subject
+        existing = db.execute(
+          "SELECT id FROM memories WHERE cart_id = ? AND subject = ?",
+          [db_cart[:id], training_mem.subject]
+        ).first
+
+        if existing
+          skipped += 1
+        else
+          mem.store(subject: training_mem.subject, content: training_mem.content)
+          stored += 1
+        end
+      end
+
+      {stored: stored, skipped: skipped, total: cart.memory_count, cart_id: db_cart[:id]}
+    end
+
+    # List available .pcart files.
+    #
+    # @return [Array<String>] Sorted list of cart file paths
+    def list_carts
+      return [] unless Dir.exist?(@carts_dir)
+      Dir.glob(File.join(@carts_dir, "*#{EXTENSION}")).sort
+    end
+
+    # Get quick info about a cart without fully loading it.
+    #
+    # @param path [String] Path to the cart file
+    # @return [Hash]
+    def cart_info(path)
+      require "zip"
+      Zip::File.open(path) do |zf|
+        entry = zf.find_entry("persona.yml")
+        return {error: "Missing persona.yml"} unless entry
+
+        data = YAML.safe_load(entry.get_input_stream.read, permitted_classes: [Date, Time]) || {}
+        {
+          tag: data.fetch("tag", File.basename(path, EXTENSION)),
+          version: data.fetch("version", "").to_s,
+          memory_count: Array(data.fetch("memories", [])).size
+        }
+      end
+    rescue => e
+      {error: e.message}
+    end
+
+    private
+
+    def parse_memories(list)
+      return [] unless list.is_a?(Array)
+
+      list.filter_map do |item|
+        next unless item.is_a?(Hash) && item["subject"] && item["content"]
+        content = item["content"]
+        content = content.map(&:to_s).join(", ") if content.is_a?(Array)
+        TrainingMemory.new(subject: item["subject"].to_s, content: content.to_s)
+      end
+    end
+  end
+end

data/lib/personality/cli/cart.rb

@@ -53,6 +53,173 @@ module Personality
         puts "#{Pastel.new.green("Created:")} #{cart[:tag]} (id: #{cart[:id]})"
       end
 
+      desc "teach FILE", "Learn a persona from a training YAML file"
+      option :output, type: :string, aliases: "-o", desc: "Output .pcart path"
+      option :import, type: :boolean, default: true, desc: "Import memories into database"
+      def teach(file)
+        require_relative "../cart_manager"
+        require_relative "../db"
+        require "pastel"
+        require "tty-spinner"
+
+        pastel = Pastel.new
+        manager = CartManager.new
+
+        # Parse and create .pcart
+        spinner = TTY::Spinner.new("  :spinner Parsing training file...", format: :dots)
+        spinner.auto_spin
+        cart = manager.create_from_training(file, output_path: options[:output])
+        spinner.success(pastel.green("#{cart.name} — #{cart.memory_count} memories"))
+
+        puts "  #{pastel.dim("Tag:")} #{cart.tag}"
+        puts "  #{pastel.dim("Version:")} #{cart.version}" unless cart.version.to_s.empty?
+        puts "  #{pastel.dim("Voice:")} #{cart.voice}" if cart.voice && !cart.voice.empty?
+        puts "  #{pastel.dim("Cart:")} #{cart.path}"
+
+        # Import memories into DB
+        if options[:import]
+          spinner = TTY::Spinner.new("  :spinner Importing memories...", format: :dots)
+          spinner.auto_spin
+          result = manager.import_memories(cart)
+          spinner.success(pastel.green("#{result[:stored]} stored, #{result[:skipped]} skipped"))
+        end
+
+        # Show persona instructions preview
+        require_relative "../persona_builder"
+        builder = PersonaBuilder.new
+        summary = builder.build_summary(cart)
+        puts "\n  #{pastel.bold(summary)}"
+        puts "  #{pastel.dim("Run `psn cart show #{cart.tag}` for full instructions")}"
+      end
+
+      desc "teach-all DIR", "Learn all personas from a training directory"
+      option :force, type: :boolean, default: false, aliases: "-f", desc: "Overwrite existing carts"
+      def teach_all(dir)
+        require_relative "../cart_manager"
+        require_relative "../training_parser"
+        require_relative "../db"
+        require "pastel"
+
+        pastel = Pastel.new
+        parser = TrainingParser.new
+        manager = CartManager.new
+
+        files = parser.list_files(dir)
+        if files.empty?
+          puts pastel.dim("No training files found in #{dir}")
+          return
+        end
+
+        puts pastel.bold("Found #{files.size} training files\n")
+
+        files.each do |file|
+          tag = File.basename(file, ".*").downcase
+          cart_path = File.join(manager.carts_dir, "#{tag}.pcart")
+
+          if File.exist?(cart_path) && !options[:force]
+            puts "  #{pastel.yellow("skip")} #{tag} (already exists, use --force)"
+            next
+          end
+
+          begin
+            cart = manager.create_from_training(file)
+            result = manager.import_memories(cart)
+            puts "  #{pastel.green("✓")} #{cart.name} — #{cart.memory_count} memories (#{result[:stored]} new)"
+          rescue => e
+            puts "  #{pastel.red("✗")} #{File.basename(file)} — #{e.message}"
+          end
+        end
+      end
+
+      desc "show [TAG]", "Show persona details and instructions"
+      option :memories, type: :boolean, default: false, aliases: "-m", desc: "Show raw memories"
+      option :instructions, type: :boolean, default: false, aliases: "-i", desc: "Show full LLM instructions"
+      def show(tag = nil)
+        require_relative "../cart_manager"
+        require_relative "../persona_builder"
+        require "pastel"
+
+        pastel = Pastel.new
+        manager = CartManager.new
+
+        # Find the cart
+        if tag
+          path = File.join(manager.carts_dir, "#{tag.downcase}.pcart")
+          unless File.exist?(path)
+            puts pastel.red("Cart not found: #{tag}")
+            return
+          end
+        else
+          carts = manager.list_carts
+          if carts.empty?
+            puts pastel.dim("No carts found. Run `psn cart teach <file>` first.")
+            return
+          end
+          path = carts.first
+        end
+
+        cart = manager.load_cart(path)
+        builder = PersonaBuilder.new
+        identity = cart.preferences&.identity
+
+        puts pastel.bold(builder.build_summary(cart))
+        puts ""
+        puts "  #{pastel.dim("Tag:")} #{cart.tag}"
+        puts "  #{pastel.dim("Version:")} #{cart.version}" unless cart.version.to_s.empty?
+        puts "  #{pastel.dim("Name:")} #{identity.full_name}" if identity && !identity.full_name.empty?
+        puts "  #{pastel.dim("Type:")} #{identity.type}" if identity && !identity.type.empty?
+        puts "  #{pastel.dim("Source:")} #{identity.source}" if identity && !identity.source.empty?
+        puts "  #{pastel.dim("Tagline:")} #{identity.tagline}" if identity && !identity.tagline.empty?
+        puts "  #{pastel.dim("Voice:")} #{cart.voice}" if cart.voice && !cart.voice.empty?
+        puts "  #{pastel.dim("Memories:")} #{cart.memory_count}"
+        puts "  #{pastel.dim("Cart:")} #{cart.path}"
+
+        if options[:memories]
+          puts "\n#{pastel.bold("Memories:")}\n\n"
+          cart.memories.each do |m|
+            puts "  #{pastel.cyan(m.subject)}"
+            puts "    #{m.content}\n\n"
+          end
+        end
+
+        if options[:instructions]
+          puts "\n#{pastel.bold("LLM Instructions:")}\n\n"
+          puts builder.build_instructions(cart)
+        end
+      end
+
+      desc "carts", "List available .pcart files"
+      def carts
+        require_relative "../cart_manager"
+        require "pastel"
+        require "tty-table"
+
+        pastel = Pastel.new
+        manager = CartManager.new
+
+        carts = manager.list_carts
+        if carts.empty?
+          puts pastel.dim("No .pcart files found. Run `psn cart teach <file>` first.")
+          return
+        end
+
+        rows = carts.map do |path|
+          info = manager.cart_info(path)
+          [
+            info[:tag] || File.basename(path, ".pcart"),
+            info[:version] || "-",
+            info[:memory_count]&.to_s || "?",
+            (File.size(path) > 1024) ? "#{(File.size(path) / 1024.0).round(1)} KB" : "#{File.size(path)} B"
+          ]
+        end
+
+        table = TTY::Table.new(
+          header: %w[Tag Version Memories Size],
+          rows: rows
+        )
+        puts table.render(:unicode, padding: [0, 1])
+      end
+
       def self.exit_on_failure?
         true
       end

data/lib/personality/cli/memory.rb

@@ -116,7 +116,7 @@ module Personality
         return unless data
 
         transcript_path = data["transcript_path"]
-        return unless transcript_path && File.exist?(transcript_path)
+        nil unless transcript_path && File.exist?(transcript_path)
 
         # Extract learnings from transcript — placeholder for future implementation
         # For now, this is a no-op hook endpoint

data/lib/personality/indexer.rb

@@ -13,7 +13,11 @@ module Personality
     def index_code(path:, project: nil, extensions: nil)
       dir = File.expand_path(path)
       proj = project || File.basename(dir)
-      exts = extensions ? extensions.map { |e| e.start_with?(".") ? e : ".#{e}" }.to_set : CODE_EXTENSIONS
+      exts = if extensions
+        extensions.map { |e| e.start_with?(".") ? e : ".#{e}" }.to_set
+      else
+        CODE_EXTENSIONS
+      end
 
       index_files(dir, proj, exts, table: "code_chunks", vec_table: "vec_code", language: true)
     end
@@ -153,8 +157,8 @@ module Personality
     end
 
     def search_table(db, table, vec_table, embedding, project:, limit:, type:)
-      if project
-        rows = db.execute(<<~SQL, [embedding.to_json, limit, project])
+      rows = if project
+        db.execute(<<~SQL, [embedding.to_json, limit, project])
           SELECT c.id, c.path, c.content, c.project, v.distance
           FROM #{vec_table} v
           INNER JOIN #{table} c ON c.id = v.chunk_id
@@ -163,7 +167,7 @@ module Personality
           ORDER BY v.distance
         SQL
       else
-        rows = db.execute(<<~SQL, [embedding.to_json, limit])
+        db.execute(<<~SQL, [embedding.to_json, limit])
           SELECT c.id, c.path, c.content, c.project, v.distance
           FROM #{vec_table} v
           INNER JOIN #{table} c ON c.id = v.chunk_id

data/lib/personality/init.rb

@@ -234,7 +234,7 @@ module Personality
     end
 
     def ensure_ollama_running
-      stdout, status = Open3.capture2e("ollama", "list")
+      _, status = Open3.capture2e("ollama", "list")
       return if status.success?
 
       puts "  #{pastel.yellow("starting")} ollama serve"

data/lib/personality/mcp/server.rb

@@ -18,7 +18,7 @@ module Personality
 
       def initialize
         @server = ::MCP::Server.new(
-          name: "personality",
+          name: "core",
           version: Personality::VERSION
         )
         @server.server_context = {}
@@ -248,6 +248,120 @@ module Personality
         end
       end
 
+      # === Persona Tools ===
+
+      def register_persona_tools
+        @server.define_tool(
+          name: "cart.teach",
+          description: "Learn a persona from a training YAML file. Creates a .pcart cartridge and imports memories into the database.",
+          input_schema: {
+            type: "object",
+            properties: {
+              training_file: {type: "string", description: "Path to the training YAML file"}
+            },
+            required: %w[training_file]
+          }
+        ) do |training_file:, server_context:, **|
+          require_relative "../cart_manager"
+          manager = Personality::CartManager.new
+          cart = manager.create_from_training(training_file)
+          result = manager.import_memories(cart)
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({
+            tag: cart.tag,
+            name: cart.name,
+            version: cart.version,
+            memory_count: cart.memory_count,
+            voice: cart.voice,
+            cart_path: cart.path,
+            imported: result
+          })}])
+        end
+
+        @server.define_tool(
+          name: "cart.show",
+          description: "Show persona details and LLM instructions for a cartridge.",
+          input_schema: {
+            type: "object",
+            properties: {
+              tag: {type: "string", description: "Persona tag (e.g. bt7274). If omitted, shows active cart."}
+            }
+          }
+        ) do |server_context:, **opts|
+          require_relative "../cart_manager"
+          require_relative "../persona_builder"
+          manager = Personality::CartManager.new
+          tag = opts[:tag]
+
+          if tag
+            path = File.join(manager.carts_dir, "#{tag.downcase}.pcart")
+            raise "Cart not found: #{tag}" unless File.exist?(path)
+          else
+            carts = manager.list_carts
+            raise "No carts found" if carts.empty?
+            path = carts.first
+          end
+
+          cart = manager.load_cart(path)
+          builder = Personality::PersonaBuilder.new
+          identity = cart.preferences&.identity
+
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({
+            tag: cart.tag,
+            name: cart.name,
+            version: cart.version,
+            type: identity&.type,
+            source: identity&.source,
+            tagline: identity&.tagline,
+            voice: cart.voice,
+            memory_count: cart.memory_count,
+            summary: builder.build_summary(cart),
+            instructions: builder.build_instructions(cart)
+          })}])
+        end
+
+        @server.define_tool(
+          name: "cart.instructions",
+          description: "Get the LLM persona instructions for the active or specified cart. Returns markdown formatted character instructions.",
+          input_schema: {
+            type: "object",
+            properties: {
+              tag: {type: "string", description: "Persona tag (optional, uses first available if omitted)"}
+            }
+          }
+        ) do |server_context:, **opts|
+          require_relative "../cart_manager"
+          require_relative "../persona_builder"
+          manager = Personality::CartManager.new
+          tag = opts[:tag]
+
+          if tag
+            path = File.join(manager.carts_dir, "#{tag.downcase}.pcart")
+            raise "Cart not found: #{tag}" unless File.exist?(path)
+          else
+            carts = manager.list_carts
+            raise "No carts found" if carts.empty?
+            path = carts.first
+          end
+
+          cart = manager.load_cart(path)
+          builder = Personality::PersonaBuilder.new
+          instructions = builder.build_instructions(cart)
+
+          ::MCP::Tool::Response.new([{type: "text", text: instructions}])
+        end
+
+        @server.define_tool(
+          name: "cart.carts",
+          description: "List available .pcart cartridge files with their metadata.",
+          input_schema: {type: "object", properties: {}}
+        ) do |server_context:, **|
+          require_relative "../cart_manager"
+          manager = Personality::CartManager.new
+          carts = manager.list_carts.map { |p| manager.cart_info(p).merge(path: p) }
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({carts: carts})}])
+        end
+      end
+
       # === Resources ===
 
       def register_resources
@@ -280,10 +394,47 @@ module Personality
         end
       end
 
+      def register_resource_tools
+        @server.define_tool(
+          name: "resource.read",
+          description: "Read an MCP resource by URI. Available resources: memory://subjects (subjects with counts), memory://stats (total memories, date range), memory://recent (last 10 memories).",
+          input_schema: {
+            type: "object",
+            properties: {
+              uri: {type: "string", description: "Resource URI (e.g. memory://subjects, memory://stats, memory://recent)"}
+            },
+            required: %w[uri]
+          }
+        ) do |uri:, server_context:, **|
+          db = Personality::DB.connection
+          cart = Personality::Cart.active
+
+          result = case uri
+          when "memory://subjects"
+            rows = db.execute("SELECT subject, COUNT(*) AS count FROM memories WHERE cart_id = ? GROUP BY subject ORDER BY count DESC", [cart[:id]])
+            {subjects: rows.map { |r| {subject: r["subject"], count: r["count"]} }}
+          when "memory://stats"
+            total = db.execute("SELECT COUNT(*) AS c FROM memories WHERE cart_id = ?", [cart[:id]]).dig(0, "c") || 0
+            subjects = db.execute("SELECT COUNT(DISTINCT subject) AS c FROM memories WHERE cart_id = ?", [cart[:id]]).dig(0, "c") || 0
+            dates = db.execute("SELECT MIN(created_at) AS oldest, MAX(created_at) AS newest FROM memories WHERE cart_id = ?", [cart[:id]]).first
+            {cart: cart[:tag], total_memories: total, total_subjects: subjects, oldest: dates&.fetch("oldest", nil), newest: dates&.fetch("newest", nil)}
+          when "memory://recent"
+            rows = db.execute("SELECT id, subject, content, created_at FROM memories WHERE cart_id = ? ORDER BY created_at DESC LIMIT 10", [cart[:id]])
+            {memories: rows.map { |r| {id: r["id"], subject: r["subject"], content: r["content"], created_at: r["created_at"]} }}
+          else
+            {error: "Unknown resource: #{uri}"}
+          end
+
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate(result)}])
+        end
+      end
+
       def register_tools
         register_memory_tools
         register_index_tools
         register_cart_tools
+        register_persona_tools
+        register_resource_tools
       end
 
       def read_memory_resource(uri)

data/lib/personality/mcp/tts_server.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "mcp/transports/stdio"
+require "json"
+require_relative "../tts"
+
+module Personality
+  module MCP
+    class TtsServer
+      def self.run
+        new.start
+      end
+
+      def initialize
+        @server = ::MCP::Server.new(
+          name: "speech",
+          version: Personality::VERSION
+        )
+        @server.server_context = {}
+        register_tools
+      end
+
+      def start
+        transport = ::MCP::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+
+      private
+
+      def register_tools
+        register_speak
+        register_stop
+        register_voices
+        register_current
+        register_download
+        register_test
+      end
+
+      def register_speak
+        @server.define_tool(
+          name: "speak",
+          description: "Speak text aloud using TTS. Synthesizes and plays audio in the background.",
+          input_schema: {
+            type: "object",
+            properties: {
+              text: {type: "string", description: "Text to speak aloud"},
+              voice: {type: "string", description: "Voice model name (optional, uses active voice if omitted)"}
+            },
+            required: %w[text]
+          }
+        ) do |text:, server_context:, **opts|
+          result = Personality::TTS.speak(text, voice: opts[:voice])
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate(result)}])
+        end
+      end
+
+      def register_stop
+        @server.define_tool(
+          name: "stop",
+          description: "Stop currently playing TTS audio.",
+          input_schema: {type: "object", properties: {}}
+        ) do |server_context:, **|
+          stopped = Personality::TTS.stop_current
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({stopped: stopped})}])
+        end
+      end
+
+      def register_voices
+        @server.define_tool(
+          name: "voices",
+          description: "List all installed TTS voice models.",
+          input_schema: {type: "object", properties: {}}
+        ) do |server_context:, **|
+          voices = Personality::TTS.list_voices
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({voices: voices, count: voices.size})}])
+        end
+      end
+
+      def register_current
+        @server.define_tool(
+          name: "current",
+          description: "Show the currently active TTS voice and whether it is installed.",
+          input_schema: {type: "object", properties: {}}
+        ) do |server_context:, **|
+          voice = Personality::TTS.active_voice
+          installed = !Personality::TTS.find_voice(voice).nil?
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate({voice: voice, installed: installed})}])
+        end
+      end
+
+      def register_download
+        @server.define_tool(
+          name: "download",
+          description: "Download a piper TTS voice model from HuggingFace.",
+          input_schema: {
+            type: "object",
+            properties: {
+              voice: {type: "string", description: "Voice name to download (e.g. en_US-lessac-medium)"}
+            },
+            required: %w[voice]
+          }
+        ) do |voice:, server_context:, **|
+          result = Personality::TTS.download_voice(voice)
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate(result)}])
+        end
+      end
+
+      def register_test
+        @server.define_tool(
+          name: "test",
+          description: "Test a TTS voice with sample text. Speaks and waits for completion.",
+          input_schema: {
+            type: "object",
+            properties: {
+              voice: {type: "string", description: "Voice to test (optional, uses active voice if omitted)"}
+            }
+          }
+        ) do |server_context:, **opts|
+          result = Personality::TTS.speak_and_wait("Hello! This is a test of the text to speech system.", voice: opts[:voice])
+          ::MCP::Tool::Response.new([{type: "text", text: JSON.generate(result)}])
+        end
+      end
+    end
+  end
+end

data/lib/personality/memory.rb

@@ -39,8 +39,8 @@ module Personality
 
       db = DB.connection
 
-      if subject
-        rows = db.execute(<<~SQL, [embedding.to_json, limit, cart_id, subject])
+      rows = if subject
+        db.execute(<<~SQL, [embedding.to_json, limit, cart_id, subject])
           SELECT m.id, m.subject, m.content, m.metadata, m.created_at, v.distance
           FROM vec_memories v
           INNER JOIN memories m ON m.id = v.memory_id
@@ -49,7 +49,7 @@ module Personality
           ORDER BY v.distance
         SQL
       else
-        rows = db.execute(<<~SQL, [embedding.to_json, limit, cart_id])
+        db.execute(<<~SQL, [embedding.to_json, limit, cart_id])
           SELECT m.id, m.subject, m.content, m.metadata, m.created_at, v.distance
           FROM vec_memories v
           INNER JOIN memories m ON m.id = v.memory_id
@@ -66,13 +66,13 @@ module Personality
     def search(subject: nil, limit: 20)
       db = DB.connection
 
-      if subject
-        rows = db.execute(
+      rows = if subject
+        db.execute(
           "SELECT id, subject, content, created_at FROM memories WHERE cart_id = ? AND subject LIKE ? ORDER BY created_at DESC LIMIT ?",
           [cart_id, "%#{subject}%", limit]
         )
       else
-        rows = db.execute(
+        db.execute(
           "SELECT id, subject, content, created_at FROM memories WHERE cart_id = ? ORDER BY created_at DESC LIMIT ?",
           [cart_id, limit]
         )

data/lib/personality/persona_builder.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Personality
+  # Builds LLM persona instructions from cartridge memories.
+  #
+  # Groups memories by their dot-notation subject taxonomy and formats
+  # them into structured markdown that teaches the LLM its character.
+  #
+  class PersonaBuilder
+    CATEGORY_TITLES = {
+      "identity" => "Identity",
+      "trait" => "Personality Traits",
+      "belief" => "Beliefs & Values",
+      "speech" => "Speech Patterns",
+      "knowledge" => "Knowledge",
+      "relationship" => "Relationships",
+      "behavior" => "Behaviors",
+      "emotion" => "Emotional Tendencies",
+      "goal" => "Goals & Motivations",
+      "memory" => "Background & Memories",
+      "quirk" => "Quirks & Mannerisms",
+      "protocol" => "Protocols",
+      "capability" => "Capabilities",
+      "logic" => "Logic & Reasoning",
+      "quote" => "Iconic Quotes",
+      "history" => "History & Backstory"
+    }.freeze
+
+    # Preferred display order for self.* sub-categories
+    SECTION_ORDER = %w[
+      identity trait protocol speech capability relationship
+      quote logic belief behavior emotion goal memory quirk knowledge history
+    ].freeze
+
+    # Build full persona instructions from a cartridge.
+    #
+    # @param cart [Cartridge] Loaded cartridge with memories and preferences
+    # @return [String] Formatted markdown instructions
+    def self.build_instructions(cart)
+      new.build_instructions(cart)
+    end
+
+    # @param cart [Cartridge]
+    # @return [String]
+    def build_instructions(cart)
+      return "" if cart.memories.nil? || cart.memories.empty?
+
+      groups = group_by_top_level(cart.memories)
+      lines = []
+
+      # Header
+      lines << "## Your Character\n\n"
+      identity = cart.preferences&.identity
+      if identity && !identity.name.empty?
+        lines << "You are **#{identity.name}**"
+        lines << ", a #{identity.type}" unless identity.type.empty?
+        lines << ".\n\n"
+      elsif !cart.tag.to_s.empty?
+        lines << "You are roleplaying as **#{cart.tag}**.\n\n"
+      end
+
+      lines << "> \"#{identity.tagline}\"\n\n" if identity && !identity.tagline.empty?
+
+      lines << "Stay in character at all times. Use the personality traits, "
+      lines << "speech patterns, and knowledge provided below.\n"
+
+      # self.* memories (the bulk of persona definition)
+      if groups.key?("self")
+        lines.concat(format_self_memories(groups.delete("self")))
+      end
+
+      # user.* memories
+      if groups.key?("user")
+        lines << "\n### User Interaction\n\n"
+        groups.delete("user").each { |m| lines << "- #{m.content}\n" }
+      end
+
+      # meta.* memories
+      if groups.key?("meta")
+        lines << "\n### Meta Information\n\n"
+        groups.delete("meta").each { |m| lines << "- #{m.content}\n" }
+      end
+
+      # identity.* already covered in header
+      groups.delete("identity")
+
+      # Remaining groups
+      groups.sort.each do |category, mems|
+        title = CATEGORY_TITLES.fetch(category, category.capitalize)
+        lines << "\n### #{title}\n\n"
+        mems.each { |m| lines << "- #{m.content}\n" }
+      end
+
+      lines.join
+    end
+
+    # Build a greeting from the cart's greeting memory.
+    #
+    # @param cart [Cartridge]
+    # @param user_name [String, nil]
+    # @return [String]
+    def build_greeting(cart, user_name: nil)
+      template = cart.memories&.find { |m|
+        m.subject.downcase.include?("greeting") || m.subject.downcase.include?("salutation")
+      }&.content
+
+      unless template
+        name = cart.preferences&.identity&.name
+        name = cart.tag if name.nil? || name.empty?
+        return "Hello, I am #{name}."
+      end
+
+      template
+        .gsub("{{USER_ID}}", user_name || "User")
+        .gsub("{{user}}", user_name || "User")
+        .gsub("{{TIME_GREETING}}", time_greeting)
+    end
+
+    # Build a brief summary for display.
+    #
+    # @param cart [Cartridge]
+    # @return [String]
+    def build_summary(cart)
+      parts = []
+      identity = cart.preferences&.identity
+
+      if identity && !identity.name.empty?
+        parts << identity.name
+      elsif !cart.tag.to_s.empty?
+        parts << cart.tag
+      end
+
+      parts << "(#{identity.type})" if identity && !identity.type.empty?
+      parts << "v#{cart.version}" if cart.version && !cart.version.empty?
+
+      parts.empty? ? "Persona loaded" : parts.join(" ")
+    end
+
+    private
+
+    def group_by_top_level(memories)
+      groups = Hash.new { |h, k| h[k] = [] }
+      memories.each do |mem|
+        category = mem.subject.split(".").first || "other"
+        groups[category] << mem
+      end
+      groups
+    end
+
+    def format_self_memories(memories)
+      lines = []
+
+      # Sub-group by second level (trait, belief, speech, etc.)
+      sub_groups = Hash.new { |h, k| h[k] = [] }
+      memories.each do |mem|
+        parts = mem.subject.split(".")
+        sub_cat = (parts.length > 1) ? parts[1] : "general"
+        sub_groups[sub_cat] << mem
+      end
+
+      # Ordered sections first
+      seen = Set.new
+      SECTION_ORDER.each do |sub_cat|
+        next unless sub_groups.key?(sub_cat)
+        title = CATEGORY_TITLES.fetch(sub_cat, sub_cat.capitalize)
+        lines << "\n### #{title}\n\n"
+        sub_groups[sub_cat].each { |m| lines << "- #{m.content}\n" }
+        seen << sub_cat
+      end
+
+      # Remaining sub-categories
+      sub_groups.sort.each do |sub_cat, mems|
+        next if seen.include?(sub_cat)
+        title = CATEGORY_TITLES.fetch(sub_cat, sub_cat.capitalize)
+        lines << "\n### #{title}\n\n"
+        mems.each { |m| lines << "- #{m.content}\n" }
+      end
+
+      lines
+    end
+
+    def time_greeting
+      hour = Time.now.hour
+      if hour < 12
+        "Good morning"
+      elsif hour < 17
+        "Good afternoon"
+      else
+        "Good evening"
+      end
+    end
+  end
+end

data/lib/personality/training_parser.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Personality
+  # Parsed training memory
+  TrainingMemory = Struct.new(:subject, :content, keyword_init: true)
+
+  # Parsed training document
+  TrainingDocument = Struct.new(:source, :format, :tag, :version, :memories, :preferences, keyword_init: true) do
+    def count
+      memories.size
+    end
+  end
+
+  # Parses YAML and JSON training files to extract persona memories.
+  #
+  # Training files define a persona's identity, traits, speech patterns,
+  # protocols, and other memories using a dot-notation subject taxonomy:
+  #
+  #   self.identity.*    - Core self-definition
+  #   self.trait.*       - Personality characteristics
+  #   self.protocol.*    - Rules of behavior
+  #   self.speech.*      - Communication patterns
+  #   self.quote.*       - Iconic lines
+  #   user.identity.*    - How to address the user
+  #   meta.system.*      - Meta configuration
+  #
+  class TrainingParser
+    SUPPORTED_EXTENSIONS = %w[.yml .yaml .json .jsonld].freeze
+
+    # Parse a training file into a TrainingDocument.
+    #
+    # @param path [String] Path to the training file
+    # @return [TrainingDocument]
+    # @raise [ArgumentError] if file format is unsupported
+    # @raise [Errno::ENOENT] if file doesn't exist
+    def parse_file(path)
+      path = File.expand_path(path)
+      raise Errno::ENOENT, "Training file not found: #{path}" unless File.exist?(path)
+
+      ext = File.extname(path).downcase
+      content = File.read(path, encoding: "utf-8")
+
+      tag, version, memories, preferences = case ext
+      when ".yml", ".yaml" then parse_yaml(content)
+      when ".json", ".jsonld" then parse_json(content)
+      else raise ArgumentError, "Unsupported file format: #{ext}"
+      end
+
+      TrainingDocument.new(
+        source: path,
+        format: ext.delete_prefix("."),
+        tag: tag,
+        version: version,
+        memories: memories,
+        preferences: preferences
+      )
+    end
+
+    # List training files in a directory.
+    #
+    # @param directory [String] Directory to scan
+    # @return [Array<String>] Sorted list of training file paths
+    def list_files(directory)
+      return [] unless Dir.exist?(directory)
+
+      Dir.glob(File.join(directory, "*.{yml,yaml,json,jsonld}"))
+        .sort_by { |p| File.basename(p).downcase }
+    end
+
+    # Validate a training file.
+    #
+    # @param path [String] Path to the training file
+    # @return [Array(Boolean, String)] [valid?, message]
+    def validate(path)
+      doc = parse_file(path)
+      if doc.count == 0
+        [false, "No memories found in file"]
+      else
+        [true, "Valid: #{doc.count} memories, tag=#{doc.tag}"]
+      end
+    rescue => e
+      [false, e.message]
+    end
+
+    private
+
+    def parse_yaml(content)
+      data = YAML.safe_load(content, permitted_classes: [Date, Time])
+      raise ArgumentError, "YAML root must be a hash" unless data.is_a?(Hash)
+
+      tag = data.fetch("tag", "").to_s
+      version = data.fetch("version", "").to_s
+      preferences = data.fetch("preferences", {})
+      preferences = {} unless preferences.is_a?(Hash)
+
+      memories = []
+
+      # Legacy identity section
+      identity = data.fetch("identity", {})
+      if identity.is_a?(Hash)
+        identity.each do |key, value|
+          memories << TrainingMemory.new(subject: "identity.#{key}", content: value.to_s) if value
+        end
+      end
+
+      # Memories section
+      parse_memory_list(data.fetch("memories", []), memories)
+
+      [tag, version, memories, preferences]
+    end
+
+    def parse_json(content)
+      data = JSON.parse(content)
+      raise ArgumentError, "JSON root must be an object" unless data.is_a?(Hash)
+
+      tag = data.fetch("tag", "").to_s
+      version = data.fetch("version", "").to_s
+      preferences = data.fetch("preferences", {})
+      preferences = {} unless preferences.is_a?(Hash)
+
+      memories = []
+
+      # Top-level identity fields
+      %w[name description personality purpose].each do |key|
+        value = data[key]
+        memories << TrainingMemory.new(subject: "identity.#{key}", content: value) if value.is_a?(String)
+      end
+
+      # Memories array
+      parse_memory_list(data.fetch("memories", []), memories)
+
+      # Knowledge graph
+      knowledge = data.fetch("knowledge", [])
+      if knowledge.is_a?(Array)
+        knowledge.each do |item|
+          next unless item.is_a?(Hash)
+          subject = item.fetch("@type", "knowledge.general").to_s
+          mem_content = (item["description"] || item["value"]).to_s
+          memories << TrainingMemory.new(subject: subject, content: mem_content) unless mem_content.empty?
+        end
+      end
+
+      [tag, version, memories, preferences]
+    end
+
+    def parse_memory_list(list, memories)
+      return unless list.is_a?(Array)
+
+      list.each do |item|
+        next unless item.is_a?(Hash)
+        subject = item["subject"].to_s
+        content = item["content"]
+        next if subject.empty? || content.nil?
+
+        # Handle list content (e.g., addressed_as: [Pilot, Pilot Cooper])
+        content = content.map(&:to_s).join(", ") if content.is_a?(Array)
+        content = content.to_s
+        next if content.empty?
+
+        memories << TrainingMemory.new(subject: subject, content: content)
+      end
+    end
+  end
+end

data/lib/personality/tts.rb

@@ -31,7 +31,7 @@ module Personality
         FileUtils.mkdir_p(DATA_DIR)
 
         # Synthesize to WAV
-        stdout, stderr, status = Open3.capture3(
+        _, stderr, status = Open3.capture3(
           piper_bin, "--model", model_path, "--output_file", WAV_FILE,
           stdin_data: text
         )

data/lib/personality/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Personality
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/personality.rb

@@ -11,6 +11,9 @@ require_relative "personality/chunker"
 require_relative "personality/hooks"
 require_relative "personality/context"
 require_relative "personality/cart"
+require_relative "personality/cart_manager"
+require_relative "personality/training_parser"
+require_relative "personality/persona_builder"
 require_relative "personality/memory"
 require_relative "personality/tts"
 require_relative "personality/indexer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: personality
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - aladac
@@ -135,6 +135,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.1
 - !ruby/object:Gem::Dependency
   name: toml-rb
   requirement: !ruby/object:Gem::Requirement
@@ -191,6 +205,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.13.2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -212,6 +240,7 @@ email:
 executables:
 - psn
 - psn-mcp
+- psn-tts
 extensions: []
 extra_rdoc_files: []
 files:
@@ -223,8 +252,10 @@ files:
 - docs/mcp-ruby-sdk.md
 - exe/psn
 - exe/psn-mcp
+- exe/psn-tts
 - lib/personality.rb
 - lib/personality/cart.rb
+- lib/personality/cart_manager.rb
 - lib/personality/chunker.rb
 - lib/personality/cli.rb
 - lib/personality/cli/cart.rb
@@ -240,7 +271,10 @@ files:
 - lib/personality/indexer.rb
 - lib/personality/init.rb
 - lib/personality/mcp/server.rb
+- lib/personality/mcp/tts_server.rb
 - lib/personality/memory.rb
+- lib/personality/persona_builder.rb
+- lib/personality/training_parser.rb
 - lib/personality/tts.rb
 - lib/personality/version.rb
 homepage: https://github.com/aladac/personality
@@ -263,7 +297,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Infrastructure layer for Claude Code
 test_files: []