memex/system/plans/flight-plan-tool-registry.org

Flight Plan: Unified Tool Registry (def-cognitive-tool)

• Phase A: Demand (Verify State)
• Phase B: Blueprint (Surgical Edits)
  • 1. Tool Registry Data Structure
  • 2. The `def-cognitive-tool` Macro
  • 3. Prompt Integration
  • 4. Recursive Loop Integration
• Phase D: Build (Implementation)
  • 1. Registry & Macro
  • 2. Tool-Belt Prompt Generator
  • 3. Integration with 'think'
  • 4. Integration with 'cognitive-loop'
• Phase C: Tester (Automated Proof)

Phase A: Demand (Verify State)

• Current state: Tools like `read-file`, `grep-search`, and `eval` are implemented as loose actuators or skill-specific functions.
• The LLM's knowledge of available tools is manually hardcoded into prompts or "guessed" based on skill names.
• Objective: Create a formal, self-documenting Tool Registry that automatically injects tool definitions into neural prompts.

Phase B: Blueprint (Surgical Edits)

1. Tool Registry Data Structure

• Define `*cognitive-tools*` hash table in `src/core.lisp`.
• Define a `cognitive-tool` struct to hold: name, description, parameters, guard, and body.

2. The `def-cognitive-tool` Macro

• Create a macro that simplifies tool definition.

3. Prompt Integration

• Update `think` in `src/neuro.lisp` to automatically inject the tool belt into the system prompt.

4. Recursive Loop Integration

• Update `cognitive-loop` to recognize and execute tool calls.

Phase D: Build (Implementation)

1. Registry & Macro

(in-package :org-agent)

(defvar *cognitive-tools* (make-hash-table :test 'equal))

(defstruct cognitive-tool name description parameters guard body)

(defmacro def-cognitive-tool (name description &key parameters guard body)
  `(setf (gethash ,(string-downcase (string name)) *cognitive-tools*)
         (make-cognitive-tool :name ,(string-downcase (string name))
                             :description ,description
                             :parameters ',parameters
                             :guard ,guard
                             :body ,body)))

2. Tool-Belt Prompt Generator

(defun generate-tool-belt-prompt ()
  (let ((output "AVAILABLE TOOLS:
You can call tools by returning a Lisp plist: (:target :tool :action :call :tool <name> :args (...))

"))
    (maphash (lambda (name tool)
               (setf output (concatenate 'string output
                                         (format nil "- ~a: ~a\n  Parameters: ~s\n\n"
                                                 name
                                                 (cognitive-tool-description tool)
                                                 (cognitive-tool-parameters tool)))))
             *cognitive-tools*)
    output))

3. Integration with 'think'

Refactor `think` to:

• Generate the tool belt prompt.
• Prepend it to the `system-prompt` in `ask-neuro`.

4. Integration with 'cognitive-loop'

Update the recursive check to:

• Handle `(:target :tool :action :call …)` specifically.
• Look up the tool in `*cognitive-tools*`.
• Execute guard -> body.

Phase C: Tester (Automated Proof)

• Refactor `eval` into a cognitive tool.
• Verify the agent can use it recursively.