feat(agent): curb concept/entity sprawl (strict entity types, name-length gate, pending buffer)

config.yaml.example

@@ -27,6 +27,25 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 #   - dataset
 #   - model
 
+# Optional: strict mode for brand-new concept/entity `create` items. Off by
+# default (backward compatible). When true:
+#   - a brand-new concept or entity name longer than 3 words is dropped
+#     (a lightweight proxy for "too specific to be reusable knowledge").
+#   - an entity whose LLM-returned type doesn't match entity_types (above)
+#     is dropped instead of coerced to "other" (entities only, concepts
+#     have no type) — useful for a narrow, domain-specific entity_types
+#     list where an "other"-typed entity usually signals a bad candidate.
+# Drops are logged as warnings, never silent.
+# strict_item_mode: false
+
+# Optional: how concept/entity pages absorb new documents on `openkb add`.
+#   rewrite   default — send the existing page's full body to the LLM and
+#             let it rewrite the whole page to incorporate the new document.
+#   append    cheaper for large/mature wikis — instead of a full rewrite,
+#             generate a short note about the new document and append it to
+#             the page under a "## Notes" heading (no full-page LLM rewrite).
+# concept_update_mode: rewrite
+
 # Optional: LLM / LiteLLM tuning. Keys are forwarded to LiteLLM; `timeout` and
 # `extra_headers` apply per request, the rest are set as litellm.<key>.
 # litellm:

examples/configuration/README.md

@@ -95,6 +95,17 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 #   - dataset
 #   - model
 
+# Optional: strict mode for brand-new concept/entity `create` items. Off by
+# default (backward compatible). When true:
+#   - a brand-new concept or entity name longer than 3 words is dropped
+#     (a lightweight proxy for "too specific to be reusable knowledge").
+#   - an entity whose LLM-returned type doesn't match entity_types (above)
+#     is dropped instead of coerced to "other" (entities only, concepts
+#     have no type) — useful for a narrow, domain-specific entity_types
+#     list where an "other"-typed entity usually signals a bad candidate.
+# Drops are logged as warnings, never silent.
+# strict_item_mode: false
+
 # Optional: LLM / LiteLLM tuning. Keys are forwarded to LiteLLM; `timeout` and
 # `extra_headers` apply per request, the rest are set as litellm.<key>.
 # litellm:
@@ -114,6 +125,8 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 | `concurrency` | `null` | Caps concurrent LLM calls OpenKB makes during ingest — both PageIndex's indexing of a long document and OpenKB's own concept/entity compilation. The two never run at once for the same document, so one setting covers both. Lower it if you hit provider rate limits or "too many open files" on large PDFs. `null` lets each stage apply its own default. |
 | `parallel_tool_calls` | unset | Whether the LLM agents (query, chat, lint, skill) may call tools in parallel. Unset keeps OpenKB's per-agent defaults; `true`/`false` force allow/sequential for every agent; `null` omits the setting (provider default). **Amazon Bedrock needs `null`** (see below). |
 | `entity_types` | 7 defaults | Custom vocabulary for entity pages. `other` is always kept. |
+| `strict_item_mode` | `false` | When `true`, drops a brand-new concept/entity name longer than 3 words, and drops an entity whose type doesn't match `entity_types` instead of coercing it to `other`. Drops are logged as warnings, never silent. |
+| `debug` | `false` | Enable per-file debug logging to `logs/<file>.log` (see below) without needing `-v` on every command. |
 | `litellm:` | – | A pass-through block for LiteLLM. See below. |
 
 ### The `litellm:` block