export declare const GOTCHAS_HELP = "# Field Notes & Gotchas\n\n## Tool Usage Pitfalls\n\n1. **Result Limits**: The `MAX_QUERY_LIMIT` is strictly 500 for most search tools. Use the optional `cursor` parameter and `next_cursor` output for O(1) keyset pagination on large datasets. Batch operations are strictly limited to `MAX_BATCH_SIZE` (50) per transaction.\n2. **Code Mode Restrictions**: The `mj_execute_code` sandbox cannot make network requests (calling `fetch()` returns a 403 `VALIDATION_ERROR` response object and Node network modules are stripped). Use it strictly for orchestrating `mj.*` API calls. If you need to hit external/HTTP endpoints or execute shell commands, you must use native OS tools outside of Code Mode. Note: `setTimeout` and `sleep(ms)` are available for minor delays, but avoid long-running operations.\n3. **Tool & Parameter Hallucinations**: Do NOT attempt to use tools that are not listed in the `memory://help` resource. If you guess incorrect parameter names, array methods, or access `Promise` objects synchronously in Code Mode, the proxy layer will intercept the mistake and return a structured `[VALIDATION_ERROR]` payload with `{ success: false }`. Read the feedback and adjust your payload rather than expecting a raw V8 crash. (Note: In-process MCP tool and argument healing is enabled by default and can be disabled globally via `--no-agent-healing` or `MCP_AGENT_HEALING=false`.)\n   - **Batch Operations:** Tools like `batch_create_entries`, `batch_update_entries`, and `batch_delete_entries` strictly require an object wrapper (e.g., `{ entries: [...] }`, `{ updates: [...] }`, `{ entry_ids: [...] }`). **NEVER** pass an array directly as the main argument.\n   - **Entry Creation Fields:** Entry creation tools require `content` for the primary markdown text. Hallucinated parameter names such as `entry`, `text`, `message`, `description`, `notes`, or `details` (as well as nested `{ entry: { ... } }` objects) are automatically healed and normalized to `content`.\n   - **Parameterless Tools & Prompts:** Tools like `rebuild_vector_index` take an empty object `{}`. Similarly, for MCP Prompts, note that some arguments are explicitly required (e.g., `project_number` in `project-status-summary` and `project-milestone-tracker`, or `pr_number` in `pr-summary`, `code-review-prep`, and `pr-retrospective`).\n   - **Diagnostic & Adapter Tools:** Ecosystem diagnostic methods like `server_info`, `server_health`, and `list_adapters` are automatically healed when called as MCP tools or via Code Mode (`mj.system.listAdapters()`, `mj.adapters()`).\n   - **Native Tool & Codebase Search Fallbacks:** Agent-native inspection tools like `grep_search`, `file_search`, `view_file`, and `list_dir` are automatically healed when autonomous healing is enabled. When invoked against the MCP server, local filesystem queries are bounded by `--allowed-io-roots` (`ALLOWED_IO_ROOTS`) and returned safely, and journal queries are seamlessly mapped to `search_entries` or resources.\n4. **Phrase Matching**: The `query` parameter in search tools supports true phrase matching. Wrap exact strings in double quotes (e.g., `\"error handling\"`) when word order and adjacency are critical.\n5. **Typo Tolerance**: FTS5 search operations automatically fall back to Levenshtein distance matching on tags and entry types if no results are found. To disable this when strict exact matching is needed, explicitly set `fuzzy_match: false`.\n6. **Team RBAC**: If the team database has at least one member registered, RBAC is active. Unregistered authors fall back to the `TEAM_DEFAULT_ROLE` (which denies access by default). Non-admin members can only modify or delete entries they originally authored.\n7. **Concurrent Edits**: When updating or deleting an entry (`update_entry`, `team_update_entry`, `delete_entry`, `team_delete_entry`), always pass `expected_version` if you know the current version to prevent silently overwriting concurrent changes. If you get a `VERSION_CONFLICT` error, re-read the latest entry state returned in the error payload, merge your changes, and retry.\n8. **Cross-Team Search**: The `cross_team_search` tool searches across multiple team databases configured via `ADDITIONAL_TEAM_DBS`. Results include a `team_db` label identifying the source database. This tool is read-only and uses FTS5 only (no semantic/vector search across DBs). Individual DB failures are non-fatal \u2014 the response includes `degraded: true` and per-DB error details.\n9. **Observability & Persistence**: If the server runs via HTTP with `--metrics-export prometheus` (or `METRICS_EXPORT`), a standard `/metrics` endpoint is exposed for external scrapers. Code Mode cannot natively fetch this endpoint; instead, use the `memory://metrics/summary`, `memory://metrics/latency`, and `memory://metrics/resources` resources to retrieve telemetry. **Metrics reset on restart** unless the `--persist-metrics` flag (or `PERSIST_METRICS` env var) is provided, which enables periodic JSON state snapshots for long-term trend analysis.\n10. **Multi-step Operations & Error Aggregation**: Tools performing batch actions (e.g., `import_markdown`, `batch_create_entries`, `batch_update_entries`, `batch_delete_entries`, `rebuild_vector_index`) will return a single `ErrorResponse` on partial failure (with `success: false`). This response contains an `aggregated_errors` array of objects (e.g. `[{ \"message\": \"Item at index 0 failed: UNIQUE constraint failed\" }]`) detailing individual item failures, while the top-level error message summarizes total success/failure counts.\n11. **Configuration Precedence & Debugging**: Server settings are resolved using strict precedence: CLI flags override Environment Variables, which override the Config File (`memory-journal.config.yaml` / `.yml` / `.json`), which overrides Defaults. If you encounter unexpected settings, you can run the server with the `--dump-config` flag. This command aggregates any startup configuration validation errors (printing them all at once rather than failing on the first one) or, if valid, prints the fully resolved configuration tree (with secrets automatically redacted as `[REDACTED]`) and exits cleanly. This is the primary method for diagnosing overriding issues.\n12. **Runtime Configuration Hot-Reloading**: Use `update_configuration` to dynamically change the `tool_filter` or briefing variables without a server restart. Both `update_configuration` and `mj_execute_code` are **always available** regardless of the active filter \u2014 you can never lock yourself out.\n\n   **Granular Tool Switching**: You can enable/disable individual tools at runtime:\n   - Add a tool: `update_configuration({ tool_filter: \"starter,+get_github_issues\" })`\n   - Remove a tool: `update_configuration({ tool_filter: \"full,-backup_journal,-restore_backup\" })`\n   - Exact whitelist: `update_configuration({ tool_filter: \"create_entry,search_entries\" })`\n   - Read `memory://tools/available` to discover all tools and their groups before enabling them.\n   \n   After calling `update_configuration`, the server emits `notifications/tools/list_changed` so MCP clients that support it automatically refresh the available tool list.\n13. **Database Encryption**: If the database requires SQLCipher encryption at rest, you must set the `DB_ENCRYPTION_KEY` environment variable when starting the server. If this key is missing or incorrect for an encrypted database, any operations will fail with a \"not a database\" error.\n14. **Scheduled Reports**: The `--report-interval` scheduler job is HTTP-only and requires `--report-webhook-url` to actually deliver reports. Without a webhook URL, the job still generates and persists report snapshots (viewable via `memory://insights/reports`) but skips delivery. Report delivery failures are logged but never crash the server.\n15. **Token Estimation & Content-Type Heuristics**: To assist you in optimizing your context window consumption, every tool execution result includes a `_meta.tokenEstimate` field. This value uses dynamic, content-type-aware heuristics to closely estimate real token costs (Prose defaults to 4.0 bytes/token; JSON payloads to 2.8 bytes/token; Code blocks to 3.2 bytes/token). Leverage this telemetry to govern your batch sizes or fallback to paginated/throttled endpoints if usage spikes.\n16. **Schema Hallucinations in Custom Scripts**: When writing standalone scripts or Code Mode execution payloads, do **NOT** write raw SQL queries against `better-sqlite3` guessing the database schema based on TypeScript interfaces. For example, the primary table is named `memory_journal` (NOT `entries`), and it **DOES NOT** have columns for `importance` or `created_by_agent`. Always rely on the built-in MCP API tools (e.g., `search_entries`, `get_recent_entries`) or Code Mode `mj` globals rather than crafting raw `SELECT` or `DELETE` statements to avoid `SqliteError: no such table` or `no such column` crashes.\n17. **Template Literals & Backticks in Code Mode**: When generating JavaScript code inside `mj_execute_code`, avoid unescaped nested backticks (`` ` ``) inside template literals (e.g., `` content: `... `.npmrc` ...` ``). Unescaped backticks prematurely terminate the template string and trigger syntax errors or tagged template TypeErrors (e.g., `TypeError: \"...\".npmrc is not a function`). Instead, pass large markdown payloads via the `context` parameter (e.g., `context: { content: \"...\" }`) and reference them as `context.content`, or escape all nested backticks with `\\`.\n18. **Result Size Cap & Auto-Compaction in Code Mode**: The Code Mode sandbox enforces a default 100KB result serialization cap to protect context windows and prevent out-of-memory crashes. If your script returns large payloads (such as querying 50+ entries with complete markdown content), pass `max_result_size: <bytes>` (e.g. `200 * 1024` or `500 * 1024`, up to 50MB) in `mj_execute_code` parameters or context, set the `CODE_MODE_MAX_RESULT_SIZE` environment variable, or select specific fields before returning. When returning oversized collections, the sandbox automatically compacts large markdown strings to preserve execution success.\n\n## GitHub & Kanban Sync\n\n- **Eventual Consistency**: GitHub Projects V2 read indexes are eventually consistent. If you `add_kanban_item` or `move_kanban_item`, a subsequent `get_kanban_board` might take up to 10 seconds to reflect the change.\n- **Multi-Project Routing**: Always pass the `repo` parameter to GitHub tools if your `memory://briefing` indicates you are in a multi-project environment.\n\n## Structural Integrity\n\n- **Session Summaries**: Always use `entry_type: \"retrospective\"` and tag with `session-summary`.\n- **References**: Never guess `entry_id`, `issue_number`, or `pr_number`. Always query them first to avoid broken links.\n- **Significance**: Only mark entries with `significance_type` if they are genuinely major milestones, decisions, or breakthroughs. Overusing this degrades the signal-to-noise ratio of the journal.";
//# sourceMappingURL=gotchas.d.ts.map