Skip to content

fix(coding-agents): exclude external facts from knowledge pages - #3484

Open
Sanderhoff-alt wants to merge 1 commit into
vectorize-io:mainfrom
Sanderhoff-alt:fix/knowledge-page-external
Open

fix(coding-agents): exclude external facts from knowledge pages#3484
Sanderhoff-alt wants to merge 1 commit into
vectorize-io:mainfrom
Sanderhoff-alt:fix/knowledge-page-external

Conversation

@Sanderhoff-alt

@Sanderhoff-alt Sanderhoff-alt commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Knowledge Pages can currently summarize a dependency's implementation or decisions as if they belonged to the repository being worked on. This happens because document attribution records where a fact was captured, but does not identify what project the fact is about. This PR adds an explicit external-knowledge classification and prevents those facts from entering the repository's standard Knowledge Pages.

Fixes #3476

What changed

The coding-agents plugin adds knowledge:external to the entity-label vocabulary. The extraction guidance says to use it only when the fact is about another project's own implementation, configuration, or decision. A decision about how the current repository uses or integrates a dependency remains normal project knowledge. The external label is explicitly exclusive with the other knowledge:* categories.

Each seeded Knowledge Page now refreshes from its normal category tag and excludes knowledge:external with a deterministic compound tag filter. The exclusion is therefore enforced by the refresh query instead of relying on wording in the page's natural-language source query.

Existing pages are upgraded in place. On startup the plugin reads the Knowledge Base tree, matches the fixed root pages by name, and patches a page only when its trigger is missing or different. Page IDs, existing content, and synthesized history are preserved. New pages receive the trigger when they are created, and repeated startup runs are idempotent.

The Knowledge Base API now exposes the page trigger in tree responses and accepts an optional trigger field in node PATCH requests. The route forwards that field to the existing backing mental-model update logic. The field is optional, so older clients and older page behavior remain compatible.

The CLI now exposes the same capability as knowledge-base update BANK NODE --trigger <JSON>. The argument accepts the complete trigger object, including nested tag_groups, and is included in the CLI OpenAPI coverage check.

The Rust SDK does not commit generated source files. Its build.rs generates the models from hindsight-docs/static/openapi.json at build time, so KnowledgeNode.trigger, UpdateNodeRequest.trigger, and nested trigger tag groups are available after rebuilding. The service's native MCP has no Knowledge Base CRUD operation, so it has no corresponding parameter to add. The coding-agents MCP also keeps page CRUD internal to the plugin.

The OpenAPI specification and generated Python, TypeScript, and Go clients are updated together with the control-plane types and wrappers.

Compatibility

The deprecated per-harness plugins continue to use their existing mental-model endpoints and are not changed by this PR. They remain operational, but they do not automatically gain the new external classification. The current unified plugin upgrades pages created by earlier versions of that same plugin when the server exposes the trigger field. Historical facts are not reclassified automatically; newly extracted facts use the new label.

When an older server does not expose the Knowledge Base surface, the plugin treats 404, 405, and 501 responses as an unavailable optional capability. It skips page creation or upgrade and continues with bank configuration and memory operations. Older servers that return a tree without trigger are not sent a trigger PATCH, so their existing page behavior is preserved.

Verification

The coding-agents test suite passed with 504 tests, including 31 Knowledge Page tests. The CLI trigger parsing test passed, the CLI compiled successfully, and the OpenAPI coverage check reported all 89 operations and 115 request parameters covered. Client and documentation generation, repository lint hooks, and whitespace checks passed. The server Knowledge Base integration tests were not run because this temporary worktree does not include pg0-embedded, so its test database cannot start.

@Sanderhoff-alt
Sanderhoff-alt force-pushed the fix/knowledge-page-external branch 4 times, most recently from d89ae89 to cb5d086 Compare August 14, 2026 10:15
Add knowledge:external as an explicit entity-label value for facts whose subject
is another project's own implementation, configuration, or decision. The label
guidance makes external mutually exclusive with the five normal
project-knowledge categories, while dependency decisions about this project
remain in the normal categories.

Give every seeded Knowledge Page a compound refresh scope that requires its
normal knowledge:* label and excludes knowledge:external. The exclusion is
implemented with deterministic tag groups, not source text. Make page seeding
idempotently repair existing pages by matching names and PATCHing only
missing or changed triggers. Existing page IDs, content, and synthesized history
are preserved.

Expose the existing backing mental-model trigger through the Knowledge Base API,
including tree responses and PATCH updates. Explicit trigger:null is
rejected with a clear 400 response instead of becoming a silent no-op. Decode
string-valued JSONB and CLOB triggers before building KnowledgeNode responses,
and compare plugin tag groups with key-order-independent JSON.

Use generated SDK models through the Python wrapper's from_dict mapping so
nested tag_groups are preserved for mental-model and page operations. Add
regression coverage for database response decoding, null-trigger rejection,
key-order-independent page synchronization, and all nested Python mappings.

Add knowledge-base update --trigger <JSON> to the CLI, including nested
tag_groups, and regenerate the OpenAPI contract and client documentation. Keep
older plugins and older servers compatible: clients ignore an unknown tree
response field, and page synchronization skips unsupported newer operations.

Validate with the full knowledge-base tests, coding-agents tests, Python wrapper
tests, CLI coverage, OpenAPI compatibility, client generation, docs generation,
lint hooks, and whitespace checks.
@Sanderhoff-alt
Sanderhoff-alt force-pushed the fix/knowledge-page-external branch from cb5d086 to 79fe095 Compare August 14, 2026 10:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant