fix(knowledge): persist document tags in agent flows

[j15z]

Summary

Agent-authored knowledge document tags now persist through create and update flows, and agents can query documents using tag filters. Document writes use the established Sim shape { tagName, value }; the runtime adapter still accepts the legacy { tagName, tagValue } shape for backward compatibility. Empty tag inputs are treated as absent so they do not block otherwise valid searches or document updates.

Related: simstudioai/mothership#360

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

• bun run lint
• bun run check:api-validation:strict
• apps/sim: bun run type-check
• bun run mship-tools:check
• apps/sim: bunx vitest run lib/copilot/tools/server/knowledge/knowledge-base.test.ts tools/knowledge/knowledge.test.ts (20 tests passing)
• apps/sim: bun run scripts/sync-tool-catalog.ts --input=/Users/justin/code/.worktrees/mothership-knowledge-document-tags/copilot/contracts/tool-catalog-v1.json --check
• apps/sim: bunx biome check lib/copilot/generated/tool-catalog-v1.ts lib/copilot/generated/tool-schemas-v1.ts lib/copilot/tools/server/knowledge/knowledge-base.test.ts

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

N/A — no UI changes.

Post-Deploy Monitoring & Validation

• During the first 24 hours after deployment, the Copilot/Knowledge owner should run a WriteMemory or update_document flow with a typed document tag and confirm the tag is visible on the saved document.
• Healthy signal: document-tag writes succeed with no tool-validation errors and the submitted tag value is persisted.
• Failure signal: { tagName, value } is rejected, or the update succeeds without the tag. If observed, revert this PR and the related Mothership PR together.

[greptile-apps]

Too many files changed for review. (183 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 20, 2026 10:41pm

[cursor]

PR Summary

Medium Risk
Changes knowledge document writes and search filtering in Copilot tools; behavior is covered by tests but affects agent memory/tag workflows.

Overview
Agent-authored knowledge tags now persist on create/update and can narrow semantic search, with empty or blank tag inputs treated as absent so they do not block other updates or queries.

Copilot knowledge_base / search_knowledge_base schemas gain documentTags and tagFilters (operators, typed values, between bounds). The server tool resolves tag display names to storage slots, validates values, and routes query through handleTagAndVectorSearch when filters apply, otherwise vector-only search.

parseDocumentTags accepts agent payloads that use tagValue instead of value. list_tags and get_tag_usage responses are wrapped as { tags } and { usage }. Tests cover tag persistence, filter routing, and empty-tag edge cases.

^{Reviewed by Cursor Bugbot for commit 7e5e5b6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7942b36. Configure here.}

[j15z]

Cursor PR Summary: “Touches knowledge document writes and search filtering paths used by Copilot/agents; changes are localized and covered by new unit tests.”

Resolution: confirmed against the current 58dfe1bb head. The summary matches the final six-file knowledge diff. Bugbot's actionable empty-tag-array finding was addressed and covered by the focused knowledge tests; the three desktop findings were against the pre-rebase head and are outside the current diff. Lint, strict API validation, Sim type-checking, the Mothership tool-contract check, and 49 focused knowledge tests pass. No further change is required for this summary.

[j15z]

Cursor Bugbot summary: “parseDocumentTags accepts agent payloads that use tagValue instead of value.”

Resolved/confirmed for the current head: the canonical documentTags contract generated from Mothership now uses { tagName, value }, matching Sim’s existing workflow/editor and ingestion shape. Sim intentionally still accepts { tagName, tagValue } as a backward-compatible fallback, then normalizes it to value before persistence. Query filters continue to use tagValue because it is the filter operand. No further action is needed on this summary.

[j15z]

Closing as superseded by mothership#360. Sim’s existing VFS already exposes the required tag metadata, so no Sim-side changes are needed.