personality 0.1.0

data/TODO.md

@@ -0,0 +1,65 @@
+# TODO
+
+## Phase 1: Foundation
+
+- [x] `db.rb` — singleton connection, sqlite-vec loading, migration runner
+- [x] Schema v2 — carts, memories, code_chunks, doc_chunks, vec0 virtual tables
+- [x] Update `init.rb` to use `db.rb` for schema creation (remove inline SQL)
+- [x] `embedding.rb` — Ollama HTTP client, `generate(text)`, 8000 char truncation
+- [x] `chunker.rb` — overlapping window splitter (2000/200)
+- [x] Tests for db, embedding, chunker
+
+## Phase 2: Hooks & Context
+
+- [x] `hooks.rb` service — JSONL logging, field truncation, config via `logging.toml`
+- [x] `cli/hooks.rb` — all 9 hook event subcommands (pre-tool-use, post-tool-use, stop, subagent-stop, session-start, session-end, user-prompt-submit, pre-compact, notification)
+- [x] `psn hooks install` — generate `hooks.json` for Claude Code settings
+- [x] `context.rb` service — session file-read tracking (`/tmp/psn-context/`)
+- [x] `cli/context.rb` — track-read, check, list, clear subcommands
+- [x] Tests for hooks and context
+
+## Phase 3: Cart & Memory
+
+- [x] `cart.rb` service — find_or_create, active, list, use, create
+- [x] `cli/cart.rb` — list, use, create subcommands
+- [x] `memory.rb` service — store, recall, search, forget, list (cart-scoped)
+- [x] `memory.rb` save hook — extract learnings from transcript (stub endpoint, ready for future impl)
+- [ ] `memory.rb` precompact hook — deduplicate memories (>0.95 similarity) [deferred: needs real usage data]
+- [x] `cli/memory.rb` — store, recall, search, forget, list, save subcommands
+- [x] Tests for cart and memory
+
+## Phase 4: TTS
+
+- [x] `tts.rb` service — piper synthesis, playback, PID tracking, voice resolution
+- [x] TTS interrupt protocol — natural stop flag, interrupt-check logic
+- [x] `cli/tts.rb` — speak, stop, mark-natural-stop, interrupt-check, voices, download, test, current
+- [x] Voice download from HuggingFace (piper-voices repo)
+- [x] Tests for TTS service
+
+## Phase 5: Indexer
+
+- [x] `indexer.rb` service — index_code, index_docs, search, status, clear, index_single_file
+- [x] `indexer.rb` hook — re-index on Write/Edit (PostToolUse)
+- [x] `cli/index.rb` — code, docs, search, status, clear, hook subcommands
+- [x] Tests for indexer
+
+## Phase 6: MCP Server
+
+- [x] `mcp/server.rb` — official `mcp` gem (0.9.1), stdio transport, define_tool API
+- [x] Memory tools — memory.store, memory.recall, memory.search, memory.forget, memory.list
+- [x] Index tools — index.code, index.docs, index.search, index.status, index.clear
+- [x] Cart tools — cart.list, cart.use, cart.create
+- [x] MCP resources — memory://subjects, memory://stats, memory://recent
+- [x] `exe/psn-mcp` — standalone MCP binary
+- [ ] `.mcp.json` template generation [deferred: trivial, can add to hooks install]
+- [x] Tests for MCP server (15 specs)
+
+## Phase 7: Integration & Polish
+
+- [x] `psn hooks session-start` — load persona instructions + intro prompt
+- [x] `psn hooks notification` — speak notifications via TTS
+- [x] End-to-end test: init → store memory → recall → verify
+- [x] End-to-end test: index code → search → verify results
+- [x] End-to-end test: MCP server protocol → tools/call → resources/read
+- [ ] CLI help text and `--help` output review
+- [ ] README update with usage examples

data/docs/mcp-ruby-sdk.md

@@ -0,0 +1,193 @@
+---
+source: https://github.com/modelcontextprotocol/ruby-sdk
+fetched: 2026-03-26
+gem: mcp (0.9.1)
+---
+
+# MCP Ruby SDK
+
+The official Ruby SDK for Model Context Protocol servers and clients.
+
+## Building an MCP Server
+
+The `MCP::Server` class handles JSON-RPC requests and responses implementing the MCP specification.
+
+### Key Features
+
+- JSON-RPC 2.0 message handling
+- Protocol initialization and capability negotiation
+- Tool registration and invocation
+- Prompt registration and execution
+- Resource registration and retrieval
+- Stdio & Streamable HTTP transports
+- Notifications for list changes (tools, prompts, resources)
+
+### Supported Methods
+
+- `initialize` - Protocol init, returns server capabilities
+- `ping` - Health check
+- `tools/list` - Lists registered tools and schemas
+- `tools/call` - Invokes a tool with arguments
+- `prompts/list` - Lists registered prompts
+- `prompts/get` - Retrieves a prompt by name
+- `resources/list` - Lists registered resources
+- `resources/read` - Retrieves a resource by URI
+- `resources/templates/list` - Lists resource templates
+
+## Defining Tools
+
+Three ways to define tools:
+
+### 1. Class definition
+
+```ruby
+class MyTool < MCP::Tool
+  tool_name "my_tool"
+  description "Does something"
+  input_schema(
+    properties: {
+      message: { type: "string" },
+    },
+    required: ["message"]
+  )
+
+  def self.call(message:, server_context:)
+    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+  end
+end
+```
+
+### 2. Tool.define
+
+```ruby
+tool = MCP::Tool.define(
+  name: "my_tool",
+  description: "Does something",
+) do |args, server_context:|
+  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
+end
+```
+
+### 3. Server#define_tool
+
+```ruby
+server.define_tool(
+  name: "my_tool",
+  description: "Does something",
+  input_schema: {
+    type: "object",
+    properties: { msg: { type: "string" } },
+    required: ["msg"]
+  }
+) do |msg:, server_context:|
+  MCP::Tool::Response.new([{ type: "text", text: msg }])
+end
+```
+
+**Important:** When using `define_tool`, arguments are passed as **keyword args** (splatted from the arguments hash). The `server_context:` keyword is always passed.
+
+### Tool Names
+
+Tool names only allow: `A-Z`, `a-z`, `0-9`, `_`, `-`, `.`
+
+**No `/` allowed.** Use dots for namespacing: `memory.store`, `index.search`.
+
+### Tool Responses
+
+Tools must return `MCP::Tool::Response`:
+
+```ruby
+MCP::Tool::Response.new([{ type: "text", text: "result" }])
+MCP::Tool::Response.new([{ type: "text", text: "error" }], error: true)
+```
+
+## Resources
+
+Register resources with the server:
+
+```ruby
+resource = MCP::Resource.new(
+  uri: "memory://subjects",
+  name: "memory-subjects",
+  description: "All subjects",
+  mime_type: "application/json",
+)
+
+server = MCP::Server.new(name: "my_server", resources: [resource])
+# or: server.resources = [resource]
+```
+
+Handle reads:
+
+```ruby
+server.resources_read_handler do |params|
+  [{
+    uri: params[:uri],
+    mimeType: "application/json",
+    text: JSON.generate({ data: "value" })
+  }]
+end
+```
+
+## Server Handle API
+
+Two methods for processing requests:
+
+```ruby
+# Hash in, Hash out (symbol keys)
+response = server.handle({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} })
+# => { jsonrpc: "2.0", id: 1, result: { tools: [...] } }
+
+# JSON string in, JSON string out
+response = server.handle_json('{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')
+# => '{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}'
+```
+
+**Must call `initialize` before other methods** — the server requires protocol handshake first.
+
+## Stdio Transport
+
+```ruby
+server = MCP::Server.new(name: "my_server", version: "1.0")
+# ... define tools, resources ...
+
+transport = MCP::Transports::StdioTransport.new(server)
+transport.open  # Blocks, reads stdin, writes stdout
+```
+
+The transport class is at `MCP::Server::Transports::StdioTransport` (require `mcp/transports/stdio`).
+
+## Client (for connecting to MCP servers)
+
+```ruby
+stdio_transport = MCP::Client::Stdio.new(
+  command: "bundle",
+  args: ["exec", "ruby", "path/to/server.rb"],
+  env: { "API_KEY" => "secret" },
+  read_timeout: 30
+)
+client = MCP::Client.new(transport: stdio_transport)
+
+tools = client.tools
+response = client.call_tool(tool: tools.first, arguments: { message: "Hello" })
+stdio_transport.close
+```
+
+## Notifications
+
+```ruby
+server.notify_tools_list_changed
+server.notify_resources_list_changed
+server.notify_log_message(data: { message: "Hello" }, level: "info")
+server.notify_progress(progress_token: "token", progress: 50, total: 100)
+```
+
+## Configuration
+
+```ruby
+# Set server context (passed to tool blocks)
+server.server_context = { user_id: 123 }
+
+# Protocol version
+server.configuration.protocol_version  # "2024-11-05"
+```

data/exe/psn

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "personality"
+
+Personality::CLI.start(ARGV)

data/exe/psn-mcp

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

data/lib/personality/cart.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "db"
+
+module Personality
+  class Cart
+    DEFAULT_TAG = "default"
+
+    class << self
+      def find_or_create(tag)
+        db = DB.connection
+        row = db.execute("SELECT * FROM carts WHERE tag = ?", [tag]).first
+
+        if row
+          row_to_hash(row)
+        else
+          db.execute(
+            "INSERT INTO carts (tag) VALUES (?)", [tag]
+          )
+          id = db.last_insert_row_id
+          {id: id, tag: tag}
+        end
+      end
+
+      def active
+        tag = ENV.fetch("PERSONALITY_CART", DEFAULT_TAG)
+        find_or_create(tag)
+      end
+
+      def list
+        db = DB.connection
+        db.execute("SELECT * FROM carts ORDER BY tag").map { |row| row_to_hash(row) }
+      end
+
+      def use(tag)
+        find_or_create(tag)
+      end
+
+      def create(tag, name: nil, type: nil, tagline: nil)
+        db = DB.connection
+        existing = db.execute("SELECT id FROM carts WHERE tag = ?", [tag]).first
+        return find_or_create(tag) if existing
+
+        db.execute(
+          "INSERT INTO carts (tag, name, type, tagline) VALUES (?, ?, ?, ?)",
+          [tag, name, type, tagline]
+        )
+        id = db.last_insert_row_id
+        {id: id, tag: tag, name: name, type: type, tagline: tagline}
+      end
+
+      def find(tag)
+        db = DB.connection
+        row = db.execute("SELECT * FROM carts WHERE tag = ?", [tag]).first
+        row ? row_to_hash(row) : nil
+      end
+
+      private
+
+      def row_to_hash(row)
+        {
+          id: row["id"],
+          tag: row["tag"],
+          version: row["version"],
+          name: row["name"],
+          type: row["type"],
+          tagline: row["tagline"],
+          source: row["source"],
+          created_at: row["created_at"],
+          updated_at: row["updated_at"]
+        }
+      end
+    end
+  end
+end

data/lib/personality/chunker.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Personality
+  module Chunker
+    MIN_LENGTH = 10
+    DEFAULT_SIZE = 2000
+    DEFAULT_OVERLAP = 200
+
+    class << self
+      def split(text, size: DEFAULT_SIZE, overlap: DEFAULT_OVERLAP)
+        return [] if text.nil? || text.length < MIN_LENGTH
+
+        return [text] if text.length <= size
+
+        chunks = []
+        start = 0
+        while start < text.length
+          chunk = text[start, size]
+          chunks << chunk
+          start += size - overlap
+        end
+
+        chunks
+      end
+    end
+  end
+end

data/lib/personality/cli/cart.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Personality
+  class CLI < Thor
+    class Cart < Thor
+      desc "list", "List all personas"
+      def list
+        require_relative "../cart"
+        require_relative "../db"
+        require "pastel"
+        require "tty-table"
+
+        DB.migrate!
+        pastel = Pastel.new
+        carts = Personality::Cart.list
+
+        if carts.empty?
+          puts pastel.dim("No personas found")
+          return
+        end
+
+        table = TTY::Table.new(
+          header: %w[ID Tag Name Type],
+          rows: carts.map { |c| [c[:id], c[:tag], c[:name] || "-", c[:type] || "-"] }
+        )
+        puts table.render(:unicode, padding: [0, 1])
+      end
+
+      desc "use TAG", "Switch active persona"
+      def use(tag)
+        require_relative "../cart"
+        require_relative "../db"
+        require "pastel"
+
+        DB.migrate!
+        cart = Personality::Cart.use(tag)
+        puts "#{Pastel.new.green("Active:")} #{cart[:tag]} (id: #{cart[:id]})"
+      end
+
+      desc "create TAG", "Create a new persona"
+      option :name, type: :string, desc: "Display name"
+      option :type, type: :string, desc: "Persona type"
+      option :tagline, type: :string, desc: "Short description"
+      def create(tag)
+        require_relative "../cart"
+        require_relative "../db"
+        require "pastel"
+
+        DB.migrate!
+        cart = Personality::Cart.create(tag, name: options[:name], type: options[:type], tagline: options[:tagline])
+        puts "#{Pastel.new.green("Created:")} #{cart[:tag]} (id: #{cart[:id]})"
+      end
+
+      def self.exit_on_failure?
+        true
+      end
+    end
+  end
+end

data/lib/personality/cli/context.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Personality
+  class CLI < Thor
+    class Context < Thor
+      desc "track-read", "Track a file read (PostToolUse hook, reads JSON from stdin)"
+      def track_read
+        require_relative "../context"
+        require_relative "../hooks"
+
+        data = Personality::Hooks.read_stdin_json
+        return unless data
+
+        file_path = data.dig("tool_input", "file_path")
+        return unless file_path
+
+        session_id = data["session_id"]
+        Personality::Context.track_read(file_path, session_id: session_id)
+      end
+
+      desc "check FILE", "Check if a file is in session context"
+      def check(file_path)
+        require_relative "../context"
+        require "pastel"
+
+        pastel = Pastel.new
+        if Personality::Context.check(file_path)
+          puts "#{pastel.green("✓")} #{file_path} is in context"
+        else
+          puts "#{pastel.dim("✗")} #{file_path} not in context"
+          exit 1
+        end
+      end
+
+      desc "list", "List all files in current session context"
+      def list
+        require_relative "../context"
+        require "pastel"
+
+        pastel = Pastel.new
+        files = Personality::Context.list
+
+        if files.empty?
+          puts pastel.dim("No files in context")
+        else
+          puts "#{pastel.bold("Files in context")} (#{files.length})"
+          files.each { |f| puts "  #{f}" }
+        end
+      end
+
+      desc "clear", "Clear session context"
+      def clear
+        require_relative "../context"
+        require "pastel"
+
+        Personality::Context.clear
+        puts Pastel.new.green("Context cleared")
+      end
+
+      def self.exit_on_failure?
+        true
+      end
+    end
+  end
+end

data/lib/personality/cli/hooks.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Personality
+  class CLI < Thor
+    class Hooks < Thor
+      desc "pre-tool-use", "PreToolUse hook — log and allow"
+      def pre_tool_use
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("PreToolUse", data)
+      end
+
+      desc "post-tool-use", "PostToolUse hook — log"
+      def post_tool_use
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("PostToolUse", data)
+      end
+
+      desc "stop", "Stop hook — log"
+      def stop
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("Stop", data)
+      end
+
+      desc "subagent-stop", "SubagentStop hook — log"
+      def subagent_stop
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("SubagentStop", data)
+      end
+
+      desc "session-start", "SessionStart hook — log, load persona, output intro"
+      def session_start
+        require_relative "../hooks"
+        require_relative "../cart"
+        require_relative "../db"
+
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("SessionStart", data)
+
+        begin
+          Personality::DB.migrate!
+          cart = Personality::Cart.active
+
+          if cart[:name] || cart[:tagline]
+            name = cart[:name] || cart[:tag]
+            puts "**Active Persona:** #{name}"
+            puts cart[:tagline] if cart[:tagline]
+            puts
+          end
+        rescue
+          # Silently continue if cart loading fails
+        end
+      end
+
+      desc "session-end", "SessionEnd hook — log"
+      def session_end
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("SessionEnd", data)
+      end
+
+      desc "user-prompt-submit", "UserPromptSubmit hook — log and allow"
+      def user_prompt_submit
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("UserPromptSubmit", data)
+      end
+
+      desc "pre-compact", "PreCompact hook — log"
+      def pre_compact
+        require_relative "../hooks"
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("PreCompact", data)
+      end
+
+      desc "notification", "Notification hook — log and speak via TTS"
+      def notification
+        require_relative "../hooks"
+        require_relative "../tts"
+
+        data = Personality::Hooks.read_stdin_json
+        Personality::Hooks.log("Notification", data)
+
+        return unless data
+
+        message = data["message"]
+        return if message.nil? || message.empty?
+
+        # Prepend project name for context
+        cwd = data["cwd"] || Dir.pwd
+        project = File.basename(cwd)
+        speech = "#{project}: #{message}"
+
+        Personality::TTS.stop_current
+        Personality::TTS.speak(speech)
+      rescue
+        # Silently continue if TTS fails
+      end
+
+      desc "install", "Generate hooks.json for Claude Code"
+      option :output, type: :string, aliases: "-o", default: "hooks.json",
+        desc: "Output file path"
+      def install
+        require_relative "../hooks"
+        output = options[:output]
+        File.write(output, Personality::Hooks.generate_hooks_json)
+        puts "Generated #{output}"
+      end
+
+      def self.exit_on_failure?
+        true
+      end
+    end
+  end
+end