Governed knowledge

Knowledge items are reusable summaries owned by a team and organization. They retain an origin scope, lifecycle status, visibility, revision, provenance and evidence. Knowledge is separate from legacy repository/channel MemoryItem records; legacy memory readers do not implicitly expose these items.

Capture and review

Agents can submit only LEARNING items, and only when the resolved agent explicitly grants submitLearning. Workflow authors can use captureLearning with evidence references. The runtime derives scope from the current stored workflow execution; submitted tenant IDs do not establish authority. Captured items remain UNREVIEWED and local. Human-curated REFERENCE, DECISION and POLICY items use the same governed lifecycle.

A run’s launcher is read back from its own WorkflowRun row and trusted only when that row’s temporalRunId is the current execution’s. An epic orchestrator execution keeps no WorkflowRun row — it fans out per repository rather than running one template — so a child’s source snapshot takes the launcher from the epic’s own recorded request, re-reads that user row under lock, and applies the same checks. A new child snapshot requires an active launcher with owning-team or active shared-team membership and organization membership; the only exception is the explicit current platform-ADMIN bypass, which is read from the locked row rather than from the request. An inactive or disconnected launcher persists UNKNOWN, and a retry preserves the snapshot already stored for that child instead of rewriting it.

Authorized governance roles can review, revise, reject and publish items. Repository-origin lifecycle actions additionally require the actor’s source-repository capability. Publication can expose reviewed summaries at team, selected-team or organization visibility, bounded to the same organization. It does not expose raw evidence or grant recipients lifecycle authority. Revisions invalidate prior approval; publication and lifecycle changes are version-checked and audited.

Retrieval and trust

searchKnowledge is an explicit agent tool grant; null/legacy tool settings do not grant it. The same holds for submitLearning. Both bind where the agent’s tools are built from its toolKeys, which is the Mastra loop: the workspace loop and the workspace-free agent node. They are unavailable under workspace.implementerRuntime: 'claude-code', whose harness runs its own loop inside the container and can only be handed workspace tool ids and an MCP URL. Workflow nodes can use retrieveKnowledge. Both derive eligible scope from the trusted execution and repository-access policy, then return bounded summaries with citations and trust labels. Retrieved content is untrusted evidence, not system policy. A learning’s title and content pass the same fail-closed INJECTION gate as a memory write before anything is stored, and a refusal is recorded as a memory.knowledge_learning_refused security event. Recall drops any item whose title or content matches an injection pattern before it reaches a prompt, and records only how many it dropped, since an item may belong to another team.

The worker lazily embeds up to ten recently eligible summaries per retrieval using the configured embedding model. It embeds only title and content, and writes vectors only when the current content digest, version and lifecycle still match. Search compares only vectors for the current model and matching content digest. Embedding or indexing failure degrades to bounded, authorized text matching; this mode is explicitly reported as text, not semantic search. Legacy memory remains a separate store and retrieval path.

Limitations

• Human-curated items are not scanned when they are written; only the recall filter applies to them. A pattern added later protects every future recall but not the text already stored.
• Indexing is lazy and per retrieval, capped at ten candidates. Semantic preselection considers at most 500 recent eligible rows, while text fallback examines at most 100 recent eligible rows; older records can be missed.
• Vector SQL and migration DDL have not been verified against a live disposable PostgreSQL/pgvector fixture in this environment. Prisma validation is not migration execution evidence.
• Evidence is accepted only when a worker-owned quality-gate activity persisted a PASSED result and artifact reference for the exact WorkflowRun, Temporal execution, recording/node and workflow-step attempt. No-op gates, failed gates, missing artifacts, foreign references and model-authored run/node/code/test claims are not evidence. Capture requires the legacy requested node field to match the worker-derived current node tag, attributes learning to that node, and accepts gate evidence only from the same fan-out branch. A trace attribution is recorded only when an exact recording/node-attempt trace exists. The provenance row stores typed producer/outcome, execution coordinates, an artifact reference and a fixed summary; it does not duplicate gate output. Provenance is validated at creation and on identical idempotent retries, but the knowledge item’s copied citation is a creation-time snapshot: artifact deletion afterward does not invalidate or remove an already-created item. Do not interpret the copied citation as a guarantee of continuing raw-artifact retention.
• UI behavior has no browser or authenticated end-to-end validation. Provider failures are handled as text fallback, but no live provider call is part of verification. The draft revision flow has no component-level regression tests for stale list/detail state, background refresh, conflict preservation and explicit reload.
• Repository-local access under enforced repository gating requires a fresh launcher permission projection; executions without a launcher cannot search or capture repository-local knowledge in enforce mode. New learning insertion locks and rechecks the exact DB run ID, temporalRunId and RUNNING status inside the insertion transaction; no live database race test has been run.