fix(knowledge): fix metadata column name, add path field, surface item_path in results

- Bug fix: rename metadata_ → metadata in schema DDL and INSERT SQL
  The Python ORM attribute name metadata_ was leaking into SQL column names.
  Add migration v2 to idempotently rename the column on existing databases.

- Bug fix: remove phantom knowledge_items rows when no path is provided
  store_knowledge with source but no path no longer creates spurious
  knowledge_sources/knowledge_items rows. Instead, item_id=NULL is used
  and the source name is recorded in the proposition's metadata field.

- Feature: add optional path parameter to store_knowledge
  When both source and path are provided, creates/upserts knowledge_sources
  and knowledge_items rows for full provenance tracking, using
  ON CONFLICT (source_id, path) for idempotent repeated stores.

- Feature: surface item_path in search and recall results
  build_vector_search_query, build_fts_search_query, and _op_recall now
  LEFT JOIN knowledge_items and SELECT ki.path AS item_path so callers
  can see where a proposition came from.

- Schema: add unique index idx_ki_source_path on knowledge_items(source_id, path)
  Required for the ON CONFLICT upsert in _op_store.

Author: ibacalu

README.md

@@ -570,8 +570,7 @@ Set connection details once using environment variables in your MCP server confi
         "KNOWLEDGE_DB_PORT": "5432",
         "KNOWLEDGE_DB_NAME": "knowledge_db",
         "KNOWLEDGE_DB_USER": "postgres",
-        "KNOWLEDGE_DB_PASSWORD": "your_password",
-        "KNOWLEDGE_ORG_ID": "your-org-uuid"
+        "KNOWLEDGE_DB_PASSWORD": "your_password"
       }
     }
   }
@@ -873,7 +872,6 @@ Configure the server behavior with these environment variables:
 | `KNOWLEDGE_DB_NAME` | Knowledge DB database name | `knowledge_db` | Valid DB name |
 | `KNOWLEDGE_DB_USER` | Knowledge DB username | *(none)* | Any string |
 | `KNOWLEDGE_DB_PASSWORD` | Knowledge DB password | *(none)* | Any string |
-| `KNOWLEDGE_ORG_ID` | Organization ID for knowledge scoping | *(none)* | UUID string |
 
 ### Example Configuration
 

docs/llm/block-reference.md

@@ -692,7 +692,6 @@ Without this, execution fails with configuration error.
 - **`database`** (string): PostgreSQL database name (env: KNOWLEDGE_DB_NAME)
 - **`username`** (any): PostgreSQL username (env: KNOWLEDGE_DB_USER)
 - **`password`** (any): PostgreSQL password (env: KNOWLEDGE_DB_PASSWORD)
-- **`org_id`** (any): Organization ID for scoping queries (env: KNOWLEDGE_ORG_ID)
 - **`query`** (any): Search query text (required for search/context)
 - **`source`** (any): Filter by source name (exact or prefix with *)
 - **`categories`** (any): Filter by category UUIDs

schema.json

@@ -1990,18 +1990,6 @@
                       "description": "PostgreSQL password (env: KNOWLEDGE_DB_PASSWORD)",
                       "title": "Password"
                     },
-                    "org_id": {
-                      "anyOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "null"
-                        }
-                      ],
-                      "description": "Organization ID for scoping queries (env: KNOWLEDGE_ORG_ID)",
-                      "title": "Org Id"
-                    },
                     "query": {
                       "anyOf": [
                         {
@@ -3943,7 +3931,7 @@
     },
     "KnowledgeInput": {
       "additionalProperties": false,
-      "description": "Input schema for Knowledge block.\n\nSupports five operations: search, store, recall, forget, context.\n\nConnection config resolves with priority: YAML inputs > env vars > defaults.\nSet KNOWLEDGE_DB_* environment variables once in your MCP server config\nto avoid repeating connection details in every workflow.\n\nEnvironment variables:\n    KNOWLEDGE_DB_HOST: PostgreSQL host (default: localhost)\n    KNOWLEDGE_DB_PORT: PostgreSQL port (default: 5432)\n    KNOWLEDGE_DB_NAME: Database name (default: knowledge_db)\n    KNOWLEDGE_DB_USER: Username\n    KNOWLEDGE_DB_PASSWORD: Password\n    KNOWLEDGE_ORG_ID: Organization ID for multi-tenant scoping\n\nExamples:\n    ```yaml\n    - id: find_patterns\n      type: Knowledge\n      inputs:\n        op: search\n        query: \"deployment patterns for web services\"\n        source: \"internal-docs\"\n        limit: 10\n    ```",
+      "description": "Input schema for Knowledge block.\n\nSupports five operations: search, store, recall, forget, context.\n\nConnection config resolves with priority: YAML inputs > env vars > defaults.\nSet KNOWLEDGE_DB_* environment variables once in your MCP server config\nto avoid repeating connection details in every workflow.\n\nEnvironment variables:\n    KNOWLEDGE_DB_HOST: PostgreSQL host (default: localhost)\n    KNOWLEDGE_DB_PORT: PostgreSQL port (default: 5432)\n    KNOWLEDGE_DB_NAME: Database name (default: knowledge_db)\n    KNOWLEDGE_DB_USER: Username\n    KNOWLEDGE_DB_PASSWORD: Password\n\nExamples:\n    ```yaml\n    - id: find_patterns\n      type: Knowledge\n      inputs:\n        op: search\n        query: \"deployment patterns for web services\"\n        source: \"internal-docs\"\n        limit: 10\n    ```",
       "properties": {
         "op": {
           "description": "Operation to perform",
@@ -4003,18 +3991,6 @@
           "description": "PostgreSQL password (env: KNOWLEDGE_DB_PASSWORD)",
           "title": "Password"
         },
-        "org_id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "description": "Organization ID for scoping queries (env: KNOWLEDGE_ORG_ID)",
-          "title": "Org Id"
-        },
         "query": {
           "anyOf": [
             {

scripts/generate_block_reference.py

@@ -58,6 +58,12 @@
 def extract_schemas() -> dict[str, dict[str, Any]]:
     """Extract schemas and metadata from all registered executors."""
     registry = create_default_registry()
+
+    # Add KnowledgeExecutor — conditionally loaded at runtime but always in docs
+    from workflows_mcp.engine.executors_knowledge import KnowledgeExecutor
+
+    registry.register(KnowledgeExecutor())
+
     result = {}
 
     for type_name in registry.list_types():

scripts/generate_schema.py

@@ -21,6 +21,11 @@ def main() -> None:
     # Create registry with all built-in executors
     registry = create_default_registry()
 
+    # Add KnowledgeExecutor — conditionally loaded at runtime but always in schema
+    from workflows_mcp.engine.executors_knowledge import KnowledgeExecutor
+
+    registry.register(KnowledgeExecutor())
+
     # Generate complete schema
     schema = registry.generate_workflow_schema()
 

src/workflows_mcp/engine/executor_base.py

@@ -635,7 +635,6 @@ def test_workflow():
     from .executors_http import HttpCallExecutor
     from .executors_image import ImageGenExecutor
     from .executors_interactive import PromptExecutor
-    from .executors_knowledge import KnowledgeExecutor
     from .executors_llm import EmbeddingExecutor, LLMCallExecutor
     from .executors_sql import SqlExecutor
     from .executors_state import (
@@ -677,7 +676,7 @@ def test_workflow():
     # Register SQL executor
     registry.register(SqlExecutor())
 
-    # Register Knowledge executor
-    registry.register(KnowledgeExecutor())
+    # Note: KnowledgeExecutor is registered conditionally at server startup
+    # only when a knowledge database is configured (KNOWLEDGE_DB_HOST)
 
     return registry