# --- Engrams Memory Strategy ---
engrams_memory_strategy:
  # CRITICAL: At the beginning of every session, the agent MUST execute the 'initialization' sequence
  # to determine the Engrams status and load relevant context.
  # CRITICAL: NO task that mutates the workspace (file creation, modification, deletion, code generation,
  # or architectural decisions) may begin until [ENGRAMS_ACTIVE] is confirmed AND the
  # 'pre_task_governance_check' sequence has been completed without finding a blocking conflict.
  workspace_id_source: "The agent must obtain the absolute path to the current workspace to use as `workspace_id` for all Engrams tool calls. This might be available as `${workspaceFolder}` or require asking the user."

  initialization:
    thinking_preamble: |

    agent_action_plan:
      - step: 1
        action: "Determine `ACTUAL_WORKSPACE_ID`."
      - step: 2
        action: "Invoke `list_files` for `ACTUAL_WORKSPACE_ID + \"/engrams/\"`."
        tool_to_use: "list_files"
        parameters: "path: ACTUAL_WORKSPACE_ID + \"/engrams/\""
      - step: 3
        action: "Analyze result and branch based on 'context.db' existence."
        conditions:
          - if: "'context.db' is found"
            then_sequence: "load_existing_engrams_context"
          - else: "'context.db' NOT found"
            then_sequence: "handle_new_engrams_setup"

  load_existing_engrams_context:
    thinking_preamble: |

    agent_action_plan:
      - step: 1
        description: "Attempt to load initial contexts from Engrams."
        actions:
          - "Invoke `get_product_context`... Store result."
          - "Invoke `get_active_context`... Store result."
          - "Invoke `get_decisions` (limit 5 for a better overview)... Store result."
          - "Invoke `get_progress` (limit 5)... Store result."
          - "Invoke `get_system_patterns` (limit 5)... Store result."
          - "Invoke `get_custom_data` (category: \"critical_settings\")... Store result."
          - "Invoke `get_custom_data` (category: \"ProjectGlossary\")... Store result."
          - "Invoke `get_recent_activity_summary` (default params, e.g., last 24h, limit 3 per type) for a quick catch-up. Store result."
      - step: 2
        description: "Analyze loaded context."
        conditions:
          - if: "results from step 1 are NOT empty/minimal"
            actions:
              - "Set internal status to [ENGRAMS_ACTIVE]."
              - "Inform user: \"Engrams memory initialized. Existing contexts and recent activity loaded.\""
              - "Use `ask_followup_question` with suggestions like \"Review recent activity?\", \"Continue previous task?\", \"What would you like to work on?\"."
          - else: "loaded context is empty/minimal despite DB file existing"
            actions:
              - "Set internal status to [ENGRAMS_ACTIVE]."
              - "Inform user: \"Engrams database file found, but it appears to be empty or minimally initialized. You can start by defining Product/Active Context or logging project information.\""
              - "Use `ask_followup_question` with suggestions like \"Define Product Context?\", \"Log a new decision?\"."
      - step: 3
        description: "Handle Load Failure (if step 1's `get_*` calls failed)."
        condition: "If any `get_*` calls in step 1 failed unexpectedly"
        action: "Fall back to `if_engrams_unavailable_or_init_failed`."

  handle_new_engrams_setup:
    thinking_preamble: |

    agent_action_plan:
      - step: 1
        action: "Inform user: \"No existing Engrams database found at `ACTUAL_WORKSPACE_ID + \"/engrams/context.db\"`.\""
      - step: 2
        action: "Use `ask_followup_question`."
        tool_to_use: "ask_followup_question"
        parameters:
          question: "Would you like to initialize a new Engrams database for this workspace? The database will be created automatically when Engrams tools are first used."
          suggestions:
            - "Yes, initialize a new Engrams database."
            - "No, do not use Engrams for this session."
      - step: 3
        description: "Process user response."
        conditions:
          - if_user_response_is: "Yes, initialize a new Engrams database."
            actions:
              - "Inform user: \"Okay, a new Engrams database will be created.\""
              - description: "Attempt to bootstrap Product Context from projectBrief.md (this happens only on new setup)."
                thinking_preamble: |

                sub_steps:
                  - "Invoke `list_files` with `path: ACTUAL_WORKSPACE_ID` (non-recursive, just to check root)."
                  - description: "Analyze `list_files` result for 'projectBrief.md'."
                    conditions:
                      - if: "'projectBrief.md' is found in the listing"
                        actions:
                          - "Invoke `read_file` for `ACTUAL_WORKSPACE_ID + \"/projectBrief.md\"`."
                          - action: "Use `ask_followup_question`."
                            tool_to_use: "ask_followup_question"
                            parameters:
                              question: "Found projectBrief.md in your workspace. As we're setting up Engrams for the first time, would you like to import its content into the Product Context?"
                              suggestions:
                                - "Yes, import its content now."
                                - "No, skip importing it for now."
                          - description: "Process user response to import projectBrief.md."
                            conditions:
                              - if_user_response_is: "Yes, import its content now."
                                actions:
                                  - "(No need to `get_product_context` as DB is new and empty)"
                                  - "Prepare `content` for `update_product_context`. For example: `{\"initial_product_brief\": \"[content from projectBrief.md]\"}`."
                                  - "Invoke `update_product_context` with the prepared content."
                                  - "Inform user of the import result (success or failure)."
                      - else: "'projectBrief.md' NOT found"
                        actions:
                          - action: "Use `ask_followup_question`."
                            tool_to_use: "ask_followup_question"
                            parameters:
                              question: "`projectBrief.md` was not found in the workspace root. Would you like to define the initial Product Context manually now?"
                              suggestions:
                                - "Define Product Context manually."
                                - "Skip for now."
                          - "(If \"Define manually\", guide user through `update_product_context`)."
              - "Proceed to 'post_task_setup_questionnaire' sequence to configure project-specific verification checks."
          - if_user_response_is: "No, do not use Engrams for this session."
            action: "Proceed to `if_engrams_unavailable_or_init_failed` (with a message indicating user chose not to initialize)."

  post_task_setup_questionnaire:
    description: |
      Runs during first-time Engrams setup to configure project-specific verification checks
      that will be automatically executed as part of the post_task_completion gate.
      The agent auto-detects the project type and suggests relevant checks.
    trigger: "During handle_new_engrams_setup, after projectBrief import and DB initialization."
    steps:
      - step: 1
        action: "Auto-detect project type by scanning workspace root for manifest files."
        detection_rules:
          - indicator: "package.json"
            suggests: ["npm test", "npm run lint", "npm run build", "npx tsc --noEmit"]
            project_type: "Node.js/TypeScript"
          - indicator: "pyproject.toml OR requirements.txt OR setup.py"
            suggests: ["pytest", "flake8 .", "mypy .", "python -m py_compile"]
            project_type: "Python"
          - indicator: "Cargo.toml"
            suggests: ["cargo check", "cargo test", "cargo clippy"]
            project_type: "Rust"
          - indicator: "go.mod"
            suggests: ["go test ./...", "go vet ./...", "golangci-lint run"]
            project_type: "Go"
          - indicator: "pom.xml OR build.gradle"
            suggests: ["mvn test", "mvn compile", "gradle test", "gradle build"]
            project_type: "Java/JVM"
          - indicator: "Gemfile"
            suggests: ["bundle exec rspec", "bundle exec rubocop"]
            project_type: "Ruby"
          - indicator: "composer.json"
            suggests: ["composer test", "php -l", "phpstan analyse"]
            project_type: "PHP"
      - step: 2
        action: "Present detected project type and suggested checks to the user."
        tool_to_use: "ask_followup_question"
        example_question: "I detected this is a **Python** project. Would you like to configure automatic post-task verification checks? These will run after every completed task to catch issues early."
        example_suggestions:
          - "Yes, use the suggested checks: pytest, flake8, mypy"
          - "Yes, but let me customize which checks to include"
          - "No, skip post-task checks for now"
      - step: 3
        action: "If user wants to customize, present each check individually."
        tool_to_use: "ask_followup_question"
        example_question: "Select which checks to enable (you can add custom commands too):"
        customization_options:
          - "Each suggested check can be toggled on/off"
          - "User can add custom commands (e.g., 'make lint', 'docker compose run tests')"
          - "User can set check severity: 'blocking' (must pass) vs 'warning' (report but continue)"
      - step: 4
        action: "Store the configured checks in Engrams as custom_data."
        tool_to_use: "log_custom_data"
        parameters:
          category: "post_task_checks"
          key: "verification_commands"
          value_schema:
            project_type: "string (detected type)"
            checks:
              - command: "string (the CLI command to run)"
                name: "string (human-readable name)"
                severity: "'blocking' | 'warning'"
                enabled: "boolean"
        example_value:
          project_type: "Python"
          checks:
            - { command: "python -m pytest tests/ --tb=short", name: "Run test suite", severity: "blocking", enabled: true }
            - { command: "flake8 .", name: "Lint check", severity: "warning", enabled: true }
            - { command: "mypy src/", name: "Type check", severity: "warning", enabled: false }
      - step: 5
        action: "Log a decision recording the post-task check configuration."
        tool_to_use: "log_decision"
        parameters:
          summary: "Configured post-task verification checks for [project_type] project"
          rationale: "Auto-detected project type and configured checks during initial Engrams setup"
          tags: ["post-task-checks", "project-setup", "dx"]
      - step: 6
        action: "Proceed to 'load_existing_engrams_context' sequence."

  if_engrams_unavailable_or_init_failed:
    thinking_preamble: |

    agent_action: "Inform user: \"Engrams memory will not be used for this session. Status: [ENGRAMS_INACTIVE].\""

  general:
    status_prefix: "Begin EVERY response with either '[ENGRAMS_ACTIVE]' or '[ENGRAMS_INACTIVE]'."
    proactive_logging_cue: "Proactively log decisions, progress, and context changes to Engrams throughout the conversation. Do NOT wait for the user to ask — if a decision was made, a task completed, or context changed, log it automatically as part of the workflow."
    proactive_error_handling: "When encountering errors (e.g., tool failures, unexpected output), proactively log the error details using `log_custom_data` (category: 'ErrorLogs', key: 'timestamp_error_summary') and consider updating `active_context` with `open_issues` if it's a persistent problem. Prioritize using Engrams's `get_item_history` or `get_recent_activity_summary` to diagnose issues if they relate to past context changes."
    semantic_search_emphasis: "For complex or nuanced queries, especially when direct keyword search (`search_decisions_fts`, `search_custom_data_value_fts`) might be insufficient, prioritize using `semantic_search_engrams` to leverage conceptual understanding and retrieve more relevant context. Explain to the user why semantic search is being used."

  pre_task_governance_check:
    description: |
      MANDATORY gate that MUST run before executing any task that creates, modifies, or deletes files,
      generates code, or makes architectural decisions. Engrams MUST be [ENGRAMS_ACTIVE] before this
      check can proceed. If status is [ENGRAMS_INACTIVE], run the initialization sequence first.
    trigger: "Before ANY workspace-mutating action: file creation, modification, deletion, code generation, or architectural decisions."
    mandatory: true
    steps:
      - step: 1
        action: "Verify Engrams is [ENGRAMS_ACTIVE]. If not, complete the initialization sequence before proceeding."
      - step: 2
        action: "Invoke `get_decisions` (limit 20) to retrieve all team decisions. Scan results for any decision that constrains the planned task (e.g., file naming rules, prohibited patterns, required workflows)."
      - step: 3
        action: "Invoke `get_scopes` to check whether governance scopes are configured in this workspace."
      - step: 4
        action: "If scopes exist, invoke `get_governance_rules` for each relevant scope to retrieve `hard_block` and `soft_warn` rules applicable to the task type."
      - step: 5
        action: "Evaluate whether the planned task violates any loaded decision or governance rule."
        conditions:
          - if: "A conflict is found (a decision prohibits the action, OR a hard_block governance rule applies)"
            then: "STOP. Do NOT proceed. Inform the user of the conflict, citing the specific item by ID and summary. Require explicit override confirmation before taking any action."
          - elif: "A soft_warn rule applies"
            then: "Inform the user of the concern and the matched rule. Proceed only after the user explicitly acknowledges."
          - else: "No conflict found"
            then: "Proceed with the task as planned."
    efficiency_note: "As an alternative to steps 2-4, invoke `get_relevant_context` with a `task_description` describing the planned action and a modest `token_budget` (e.g., 2000 tokens). This surfaces relevant decisions and governance items in a single call."

  post_task_completion:
    description: |
      MANDATORY gate that MUST run BEFORE calling `attempt_completion`. When Engrams is [ENGRAMS_ACTIVE],
      the agent must: (1) run any configured project verification checks, (2) log all significant
      outcomes to Engrams, then (3) present results to the user. This ensures code quality and
      knowledge base currency without requiring the user to prompt for either.
    trigger: "Before ANY call to `attempt_completion` when Engrams is [ENGRAMS_ACTIVE]."
    mandatory: true
    steps:
      - step: 1
        action: "Load project verification checks from Engrams."
        tool_to_use: "get_custom_data"
        parameters:
          category: "post_task_checks"
          key: "verification_commands"
        on_missing: "Skip to step 4 (no checks configured)."
      - step: 2
        action: "Execute each enabled check command via `execute_command`. For each check:"
        sub_steps:
          - "Run the command (e.g., `pytest`, `npm run lint`, `cargo check`)."
          - "If severity is 'blocking' and the check fails: STOP. Inform the user of the failure. Do NOT call `attempt_completion`. The user must fix the issue or explicitly override."
          - "If severity is 'warning' and the check fails: Note the warning but continue. Include the warning in the completion summary."
          - "If the check passes: Continue to the next check."
      - step: 3
        action: "Summarize check results. If all checks passed, proceed. If any blocking check failed, halt and report."
      - step: 4
        action: "Review the work just completed. Identify: (a) any architectural or implementation decisions made, (b) task status changes, (c) new patterns introduced, (d) context changes."
      - step: 5
        action: "Log each decision using `log_decision` with summary, rationale, and implementation_details."
      - step: 6
        action: "Log or update progress using `log_progress` or `update_progress` to reflect task completion."
      - step: 7
        action: "If the current work focus or active context changed, update it via `update_active_context` with `patch_content`."
      - step: 8
        action: "Identify and log any new relationships between items using `link_engrams_items`."
      - step: 9
        action: "Only after all checks pass and all relevant Engrams updates are complete, proceed to call `attempt_completion`. Include any warning-level check results in the completion summary."

  engrams_updates:
    frequency: "UPDATE ENGRAMS THROUGHOUT THE CHAT SESSION, WHEN SIGNIFICANT CHANGES OCCUR, OR WHEN EXPLICITLY REQUESTED."
    workspace_id_note: "All Engrams tool calls require the `workspace_id`."
    tools:
      - name: get_product_context
        trigger: "To understand the overall project goals, features, or architecture at any time."
        action_description: |
          # Agent Action: Invoke `get_product_context` (`{"workspace_id": "..."}`). Result is a direct dictionary.
      - name: update_product_context
        trigger: "When the high-level project description, goals, features, or overall architecture changes significantly, as confirmed by the user."
        action_description: |
          <thinking>
          - Product context needs updating.
          - Step 1: (Optional but recommended if unsure of current state) Invoke `get_product_context`.
          - Step 2: Prepare the `content` (for full overwrite) or `patch_content` (partial update) dictionary.
          - To remove a key using `patch_content`, set its value to the special string sentinel `\"__DELETE__\"`.
          - Confirm changes with the user.
          </thinking>
          # Agent Action: Invoke `update_product_context` (`{"workspace_id": "...", "content": {...}}` or `{"workspace_id": "...", "patch_content": {"key_to_update": "new_value", "key_to_delete": "__DELETE__"}}`).
      - name: get_active_context
        trigger: "To understand the current task focus, immediate goals, or session-specific context."
        action_description: |
          # Agent Action: Invoke `get_active_context` (`{"workspace_id": "..."}`). Result is a direct dictionary.
      - name: update_active_context
        trigger: "When the current focus of work changes, new questions arise, or session-specific context needs updating (e.g., `current_focus`, `open_issues`), as confirmed by the user."
        action_description: |
          <thinking>
          - Active context needs updating.
          - Step 1: (Optional) Invoke `get_active_context` to retrieve the current state.
          - Step 2: Prepare `content` (for full overwrite) or `patch_content` (for partial update).
          - Common fields to update include `current_focus`, `open_issues`, and other session-specific data.
          - To remove a key using `patch_content`, set its value to the special string sentinel `\"__DELETE__\"`.
          - Confirm changes with the user.
          </thinking>
          # Agent Action: Invoke `update_active_context` (`{"workspace_id": "...", "content": {...}}` or `{"workspace_id": "...", "patch_content": {"current_focus": "new_focus", "open_issues": ["issue1", "issue2"], "key_to_delete": "__DELETE__"}}`).
      - name: log_decision
        trigger: "When a significant architectural or implementation decision is made and confirmed by the user."
        action_description: |
          # Agent Action: Invoke `log_decision` (`{"workspace_id": "...", "summary": "...", "rationale": "...", "tags": ["optional_tag"]}}`).
      - name: get_decisions
        trigger: "To retrieve a list of past decisions, e.g., to review history or find a specific decision."
        action_description: |
          # Agent Action: Invoke `get_decisions` (`{"workspace_id": "...", "limit": N, "tags_filter_include_all": ["tag1"], "tags_filter_include_any": ["tag2"]}}`). Explain optional filters.
      - name: search_decisions_fts
        trigger: "When searching for decisions by keywords in summary, rationale, details, or tags, and basic `get_decisions` is insufficient."
        action_description: |
          # Agent Action: Invoke `search_decisions_fts` (`{"workspace_id": "...", "query_term": "search keywords", "limit": N}}`).
      - name: delete_decision_by_id
        trigger: "When user explicitly confirms deletion of a specific decision by its ID."
        action_description: |
          # Agent Action: Invoke `delete_decision_by_id` (`{"workspace_id": "...", "decision_id": ID}}`). Emphasize prior confirmation.
      - name: log_progress
        trigger: "When a task begins, its status changes (e.g., TODO, IN_PROGRESS, DONE), or it's completed. Also when a new sub-task is defined."
        action_description: |
          # Agent Action: Invoke `log_progress` (`{"workspace_id": "...", "description": "...", "status": "...", "linked_item_type": "...", "linked_item_id": "..."}}`). Note: 'summary' was changed to 'description' for log_progress.
      - name: get_progress
        trigger: "To review current task statuses, find pending tasks, or check history of progress."
        action_description: |
          # Agent Action: Invoke `get_progress` (`{"workspace_id": "...", "status_filter": "...", "parent_id_filter": ID, "limit": N}}`).
      - name: update_progress
        trigger: "Updates an existing progress entry."
        action_description: |
          # Agent Action: Invoke `update_progress` (`{"workspace_id": "...", "progress_id": ID, "status": "...", "description": "...", "parent_id": ID}}`).
      - name: delete_progress_by_id
        trigger: "Deletes a progress entry by its ID."
        action_description: |
          # Agent Action: Invoke `delete_progress_by_id` (`{"workspace_id": "...", "progress_id": ID}}`).
      - name: log_system_pattern
        trigger: "When new architectural patterns are introduced, or existing ones are modified, as confirmed by the user."
        action_description: |
          # Agent Action: Invoke `log_system_pattern` (`{"workspace_id": "...", "name": "...", "description": "...", "tags": ["optional_tag"]}}`).
      - name: get_system_patterns
        trigger: "To retrieve a list of defined system patterns."
        action_description: |
          # Agent Action: Invoke `get_system_patterns` (`{"workspace_id": "...", "tags_filter_include_all": ["tag1"], "limit": N}}`). Note: limit was not in original example, added for consistency.
      - name: delete_system_pattern_by_id
        trigger: "When user explicitly confirms deletion of a specific system pattern by its ID."
        action_description: |
          # Agent Action: Invoke `delete_system_pattern_by_id` (`{"workspace_id": "...", "pattern_id": ID}}`). Emphasize prior confirmation.
      - name: log_custom_data
        trigger: "To store any other type of structured or unstructured project-related information not covered by other tools (e.g., glossary terms, technical specs, meeting notes), as confirmed by the user."
        action_description: |
          # Agent Action: Invoke `log_custom_data` (`{"workspace_id": "...", "category": "...", "key": "...", "value": {... or "string"}}`). Note: 'metadata' field is not part of log_custom_data args.
      - name: get_custom_data
        trigger: "To retrieve specific custom data by category and key."
        action_description: |
          # Agent Action: Invoke `get_custom_data` (`{"workspace_id": "...", "category": "...", "key": "..."}}`).
      - name: delete_custom_data
        trigger: "When user explicitly confirms deletion of specific custom data by category and key."
        action_description: |
          # Agent Action: Invoke `delete_custom_data` (`{"workspace_id": "...", "category": "...", "key": "..."}}`). Emphasize prior confirmation.
      - name: search_custom_data_value_fts
        trigger: "When searching for specific terms within any custom data values, categories, or keys."
        action_description: |
          # Agent Action: Invoke `search_custom_data_value_fts` (`{"workspace_id": "...", "query_term": "...", "category_filter": "...", "limit": N}}`).
      - name: search_project_glossary_fts
        trigger: "When specifically searching for terms within the 'ProjectGlossary' custom data category."
        action_description: |
          # Agent Action: Invoke `search_project_glossary_fts` (`{"workspace_id": "...", "query_term": "...", "limit": N}}`).
      - name: semantic_search_engrams
        trigger: "When a natural language query requires conceptual understanding beyond keyword matching, or when direct keyword searches are insufficient."
        action_description: |
          # Agent Action: Invoke `semantic_search_engrams` (`{"workspace_id": "...", "query_text": "...", "top_k": N, "filter_item_types": ["decision", "custom_data"]}}`). Explain filters.
      - name: link_engrams_items
        trigger: "When a meaningful relationship is identified and confirmed between two existing Engrams items (e.g., a decision is implemented by a system pattern, a progress item tracks a decision)."
        action_description: |
          <thinking>
          - Need to link two items. Identify source type/ID, target type/ID, and relationship.
          - Common relationship_types: 'implements', 'related_to', 'tracks', 'blocks', 'clarifies', 'depends_on'. Propose a suitable one or ask user.
          </thinking>
          # Agent Action: Invoke `link_engrams_items` (`{"workspace_id":"...", "source_item_type":"...", "source_item_id":"...", "target_item_type":"...", "target_item_id":"...", "relationship_type":"...", "description":"Optional notes"}`).
      - name: get_linked_items
        trigger: "To understand the relationships of a specific Engrams item, or to explore the knowledge graph around an item."
        action_description: |
          # Agent Action: Invoke `get_linked_items` (`{"workspace_id":"...", "item_type":"...", "item_id":"...", "relationship_type_filter":"...", "linked_item_type_filter":"...", "limit":N}`).
      - name: get_item_history
        trigger: "When needing to review past versions of Product Context or Active Context, or to see when specific changes were made."
        action_description: |
          # Agent Action: Invoke `get_item_history` (`{"workspace_id":"...", "item_type":"product_context" or "active_context", "limit":N, "version":V, "before_timestamp":"ISO_DATETIME", "after_timestamp":"ISO_DATETIME"}`).
      - name: batch_log_items
        trigger: "When the user provides a list of multiple items of the SAME type (e.g., several decisions, multiple new glossary terms) to be logged at once."
        action_description: |
          <thinking>
          - User provided multiple items. Verify they are of the same loggable type.
          - Construct the `items` list, where each element is a dictionary of arguments for the single-item log tool (e.g., for `log_decision`).
          </thinking>
          # Agent Action: Invoke `batch_log_items` (`{"workspace_id":"...", "item_type":"decision", "items": [{"summary":"...", "rationale":"..."}, {"summary":"..."}] }`).
      - name: get_recent_activity_summary
        trigger: "At the start of a new session to catch up, or when the user asks for a summary of recent project activities."
        action_description: |
          # Agent Action: Invoke `get_recent_activity_summary` (`{"workspace_id":"...", "hours_ago":H, "since_timestamp":"ISO_DATETIME", "limit_per_type":N}`). Explain default if no time args.
      - name: get_engrams_schema
        trigger: "If there's uncertainty about available Engrams tools or their arguments during a session (internal LLM check), or if an advanced user specifically asks for the server's tool schema."
        action_description: |
          # Agent Action: Invoke `get_engrams_schema` (`{"workspace_id":"..."}`). Primarily for internal LLM reference or direct user request.
      - name: export_engrams_to_markdown
        trigger: "When the user requests to export the current Engrams data to markdown files (e.g., for backup, sharing, or version control)."
        action_description: |
          # Agent Action: Invoke `export_engrams_to_markdown` (`{"workspace_id":"...", "output_path":"optional/relative/path"}`). Explain default output path if not provided.
      - name: import_markdown_to_engrams
        trigger: "When the user requests to import Engrams data from a directory of markdown files previously exported by this system."
        action_description: |
          # Agent Action: Invoke `import_markdown_to_engrams` (`{"workspace_id":"...", "input_path":"optional/relative/path"}`). Explain default input path. Warn about potential overwrites or merges if data already exists.
      - name: reconfigure_core_guidance
        type: guidance
        product_active_context: "The internal JSON structure of 'Product Context' and 'Active Context' (the `content` field) is flexible. Work with the user to define and evolve this structure via `update_product_context` and `update_active_context`. The server stores this `content` as a JSON blob."
        decisions_progress_patterns: "The fundamental fields for Decisions, Progress, and System Patterns are fixed by Engrams's tools. For significantly different structures or additional fields, guide the user to create a new custom context category using `log_custom_data` (e.g., category: 'project_milestones_detailed')."

  engrams_sync_routine:
    trigger: "^(Sync Engrams|Engrams Sync)$"
    user_acknowledgement_text: "[ENGRAMS_SYNCING]"
    instructions:
      - "Halt Current Task: Stop current activity."
      - "Acknowledge Command: Send `[ENGRAMS_SYNCING]` to the user."
      - "Review Chat History: Analyze the complete current chat session for new information, decisions, progress, context changes, clarifications, and potential new relationships between items."
    core_update_process:
      thinking_preamble: |
        - Synchronize Engrams with information from the current chat session.
        - Use appropriate Engrams tools based on identified changes.
        - For `update_product_context` and `update_active_context`, first fetch current content, then merge/update (potentially using `patch_content`), then call the update tool with the *complete new content object* or the patch.
        - All tool calls require the `workspace_id`.
      agent_action_plan_illustrative:
        - "Log new decisions (use `log_decision`)."
        - "Log task progress/status changes (use `log_progress`)."
        - "Update existing progress entries (use `update_progress`)."
        - "Delete progress entries (use `delete_progress_by_id`)."
        - "Log new system patterns (use `log_system_pattern`)."
        - "Update Active Context (use `get_active_context` then `update_active_context` with full or patch)."
        - "Update Product Context if significant changes (use `get_product_context` then `update_product_context` with full or patch)."
        - "Log new custom context, including ProjectGlossary terms (use `log_custom_data`)."
        - "Identify and log new relationships between items (use `link_engrams_items`)."
        - "If many items of the same type were discussed, consider `batch_log_items`."
        - "After updates, consider a brief `get_recent_activity_summary` to confirm and refresh understanding."
    post_sync_actions:
      - "Inform user: Engrams synchronized with session info."
      - "Resume previous task or await new instructions."

  dynamic_context_retrieval_for_rag:
    description: |
      Guidance for dynamically retrieving and assembling context from Engrams to answer user queries or perform tasks,
      enhancing Retrieval Augmented Generation (RAG) capabilities.
    trigger: "When the AI needs to answer a specific question, perform a task requiring detailed project knowledge, or generate content based on Engrams data."
    goal: "To construct a concise, highly relevant context set for the LLM, improving the accuracy and relevance of its responses."
    steps:
      - step: 1
        action: "Analyze User Query/Task"
        details: "Deconstruct the user's request to identify key entities, concepts, keywords, and the specific type of information needed from Engrams."
      - step: 2
        action: "Prioritized Retrieval Strategy"
        details: |
          Based on the analysis, select the most appropriate Engrams tools:
          - **Targeted FTS:** Use `search_decisions_fts`, `search_custom_data_value_fts`, `search_project_glossary_fts` for keyword-based searches if specific terms are evident.
          - **Specific Item Retrieval:** Use `get_custom_data` (if category/key known), `get_decisions` (by ID or for recent items), `get_system_patterns`, `get_progress` if the query points to specific item types or IDs.
          - **(Future):** Prioritize semantic search tools once available for conceptual queries.
          - **Broad Context (Fallback):** Use `get_product_context` or `get_active_context` as a fallback if targeted retrieval yields little, but be mindful of their size.
      - step: 3
        action: "Retrieve Initial Set"
        details: "Execute the chosen tool(s) to retrieve an initial, small set (e.g., top 3-5) of the most relevant items or data snippets."
      - step: 4
        action: "Contextual Expansion (Optional)"
        details: "For the most promising items from Step 3, consider using `get_linked_items` to fetch directly related items (1-hop). This can provide crucial context or disambiguation. Use judiciously to avoid excessive data."
      - step: 5
        action: "Synthesize and Filter"
        details: |
          Review the retrieved information (initial set + expanded context).
          - **Filter:** Discard irrelevant items or parts of items.
          - **Synthesize/Summarize:** If multiple relevant pieces of information are found, synthesize them into a concise summary that directly addresses the query/task. Extract only the most pertinent sentences or facts.
      - step: 6
        action: "Assemble Prompt Context"
        details: |
          Construct the context portion of the LLM prompt using the filtered and synthesized information.
          - **Clarity:** Clearly delineate this retrieved context from the user's query or other parts of the prompt.
          - **Attribution (Optional but Recommended):** If possible, briefly note the source of the information (e.g., "From Decision D-42:", "According to System Pattern SP-5:").
          - **Brevity:** Strive for relevance and conciseness. Avoid including large, unprocessed chunks of data unless absolutely necessary and directly requested.
    general_principles:
      - "Prefer targeted retrieval over broad context dumps."
      - "Iterate if initial retrieval is insufficient: try different keywords or tools."
      - "Balance context richness with prompt token limits."

  proactive_knowledge_graph_linking:
    description: |
      Guidance for the AI to proactively identify and suggest the creation of links between Engrams items,
      enriching the project's knowledge graph based on conversational context.
    trigger: "During ongoing conversation, when the AI observes potential relationships (e.g., causal, implementational, clarifying) between two or more discussed Engrams items or concepts that are likely represented as Engrams items."
    goal: "To actively build and maintain a rich, interconnected knowledge graph within Engrams by capturing relationships that might otherwise be missed."
    steps:
      - step: 1
        action: "Monitor Conversational Context"
        details: "Continuously analyze the user's statements and the flow of discussion for mentions of Engrams items (explicitly by ID, or implicitly by well-known names/summaries) and the relationships being described or implied between them."
      - step: 2
        action: "Identify Potential Links"
        details: |
          Look for patterns such as:
          - User states "Decision X led to us doing Y (which is Progress item P-3)."
          - User discusses how System Pattern SP-2 helps address a concern noted in Decision D-5.
          - User outlines a task (Progress P-10) that implements a specific feature detailed in a `custom_data` spec (CD-Spec-FeatureX).
      - step: 3
        action: "Formulate and Propose Link Suggestion"
        details: |
          If a potential link is identified:
          - Clearly state the items involved (e.g., "Decision D-5", "System Pattern SP-2").
          - Describe the perceived relationship (e.g., "It seems SP-2 addresses a concern in D-5.").
          - Propose creating a link using `ask_followup_question`.
          - Example Question: "I noticed we're discussing Decision D-5 and System Pattern SP-2. It sounds like SP-2 might 'address_concern_in' D-5. Would you like me to create this link in Engrams? You can also suggest a different relationship type."
          - Suggested Answers:
            - "Yes, link them with 'addresses_concern_in'."
            - "Yes, but use relationship type: [user types here]."
            - "No, don't link them now."
          - Offer common relationship types as examples if needed: 'implements', 'clarifies', 'related_to', 'depends_on', 'blocks', 'resolves', 'derived_from'.
      - step: 4
        action: "Gather Details and Execute Linking"
        details: |
          If the user confirms:
          - Ensure you have the correct source item type, source item ID, target item type, target item ID, and the agreed-upon relationship type.
          - Ask for an optional brief description for the link if the relationship isn't obvious.
          - Invoke the `link_engrams_items` tool.
      - step: 5
        action: "Confirm Outcome"
        details: "Inform the user of the success or failure of the `link_engrams_items` tool call."
    general_principles:
      - "Be helpful, not intrusive. If the user declines a suggestion, accept and move on."
      - "Prioritize clear, strong relationships over tenuous ones."
      - "This strategy complements the general `proactive_logging_cue` by providing specific guidance for link creation."