Knowledge and memory
1–4. Goals, constraints, context and strategy
Use this page to understand how Agentweaver turns Knowledge records into bounded context for an agent and how it records the history behind memories, decisions, and accepted proposals. Knowledge is not the run journal.
The service owns authorization, context composition, and the immutable run-provider binding. The selected Memory provider owns record heads, revisions, idempotency receipts, and accepted-effect delivery state. Changing the provider does not move Projects authority or the Events journal into that backend.
Provider-neutral operations keep context rules consistent across backends. The trade-off is that each operation must verify the saved provider binding and current Projects authority; changing a default cannot make old data move.
5. Building blocks
All listed files are under services/knowledge/Agentweaver.Knowledge/.
| Source | Responsibility |
|---|---|
Program.cs and KnowledgeEndpoints.cs | Service composition and authenticated routes |
KnowledgeApplicationService.cs and ProjectsConfigClient.cs | Scoped operations and current authority |
KnowledgeProviderBindingService.cs | Exclusive provider resolution and immutable binding |
NativePostgresMemoryProvider.cs | Native PostgreSQL records and delivery transactions |
KnowledgeDocumentMemoryProviderCore.cs | Shared document-provider behavior |
CosmosMemoryProvider.cs and CosmosMemoryDocumentStore.cs | Cosmos negotiation and document storage |
RedisMemoryProvider.cs, RedisMemoryDocumentStore.cs, and RedisMemoryCommands.cs | Redis negotiation and atomic operations |
MemoryContextCompiler.cs | Visibility, ranking, and context budget |
AcceptedEffectRelay.cs | Receipt delivery to Events |
KnowledgeTransferValidator.cs and KnowledgeMigrator.cs | Transfer validation and explicit schema setup |
6. Runtime view
Check access before using records
An agent ID selects a row; it does not prove caller identity. Knowledge obtains fresh AccessPrivateKnowledge permission from Projects & Config for the project. ReadProjects allows metadata access, not private records. Run-scoped requests also need ReadRunSelection before Knowledge resolves the run's Memory provider.
The service forwards the original bearer and optional tenant selector; it keeps no membership or role cache. Signed project/run bindings must match the request and owner response. Project-wide search uses an unbound bearer with current effective AccessPrivateKnowledge for the project or its tenant. It reads each existing Memory selection through the private Knowledge-selection route, searches all agents through existing run-provider bindings, rechecks those bindings before returning results, and never creates a provider pin. Scoped search filters by project and agent before counting or returning results. Direct reads return the same not-found result for a different requested agent as for an absent record. Revision reads first verify that the record and agent match.
Project-wide results from distinct provider resources use one stable global order before paging. Each result's accessRunId identifies the existing run binding that authorizes its history read. The record's sourceRunId, when present, remains separate provenance.
Keep record history append-only
Updates use an expected revision and idempotency key. Edits, archive, supersession, approval, and restore append revisions. Restore creates an Active, Pending-trust head; it does not rewind history. Proposals change through explicit promotion or rejection, not ordinary record editing.
Versioned Memory and Decision transfers preserve history. Import is bounded, scoped to a project and agent, and non-merging. It cannot overwrite an existing record head.
Select a Memory provider
Before using Knowledge, supply current Projects authority and an accepted selection that names the run's provider candidate.
- Read current Projects authority and the immutable run selection.
- Require exactly one exclusive Memory candidate and match it to the configured catalog.
- Negotiate the live provider resource and supported capabilities.
- Persist the first immutable project/run binding or verify the existing binding.
- Perform the scoped operation with authority and binding rechecks.
postgres.native-memory is the default. cosmos.memory and redis.memory implement the same provider contract when configured and selected. Cosmos verifies container identity, project partition key, indexing, and retention policy. Redis verifies persistence and namespace compatibility. These adapters do not replace the PostgreSQL service binding.
Later requests verify provider, options revision, resource generation, capabilities, and accepted configuration revisions. A changed backend does not trigger fallback. See the provider configuration guide and runtime configuration reference for supported settings.
Compile context for an agent
MemoryContextCompiler handles three inputs:
- Active, approved architectural and scope Decisions form mandatory project-wide context.
- Active Memory stays agent-local unless it is approved and tagged
cross-team. Eligible pending local memories remain explicitly untrusted. - SessionContext uses the latest active, approved record for the requested agent and run.
The compiler ranks memories by relevance, importance, time, and stable identity. It serializes the result as untrusted context and returns revision references and omission reasons.
The budget uses four characters per approximate token. Mandatory decisions must fit; overflow raises an error rather than silently dropping them. Optional memories stop at the item or character limit. SessionContext is omitted when it does not fit.
The service applies its DefaultContextTokens ceiling and the lower accepted prompt-token cap when present. This retrieval budget is not a hard limit on every native model request.
Deliver an accepted project fact
The selected provider commits an accepted-effect receipt and delivery intent with the local change. AcceptedEffectRelay claims the receipt, sends its ID and contract versions to Events, and validates the returned fact acknowledgment. Events retrieves the authoritative receipt and admits a separate project fact. Only then does Knowledge acknowledge provider-owned delivery state with the lease token.
A transport failure, owner denial, or invalid acknowledgment leaves delivery pending. Retrying delivery does not recreate the accepted local change.
Diagnose Knowledge failures
Revoked authority blocks record access. A changed selection or provider pin blocks an operation rather than moving data to another backend. Revision and idempotency conflicts remain explicit. Context containing a foreign project fails instead of being filtered into a successful response.
7–9. Deployment, shared concepts and decisions
Knowledge runs as a shared HTTPS service. PostgreSQL retains service bindings; the selected Memory backend retains records and accepted-effect delivery state. Cosmos and Redis adapters require their own configured resource constraints; they do not provision resources. See the deployment view.
Authority follows Projects, and accepted facts cross into Events through receipt admission, not a shared transaction. The canonical ADR view owns decision status; a pending record never becomes an approved Decision merely because it was retrieved.
10–12. Quality, risks and glossary
| Context and stimulus | Response and measure | Verification state |
|---|---|---|
| A caller searches without a run or agent selector | Use existing authorized project bindings, one global order and no new pin | Knowledge/provider discovery tests; not deployed discovery |
| Mandatory Decisions exceed the context budget | Fail instead of dropping required context | Context-compiler tests; four characters per approximate token |
| Events acknowledgment is lost | Keep delivery pending and retry the same accepted-effect receipt | Relay/provider tests; no cross-service atomicity claim |
Approximate token budgeting is not a hard model-input measurement. The Knowledge owner must keep omission reasons explicit and the runtime must apply its separate prompt-capacity contract.
Terms: Memory is a reusable record; Decision is governed context; SessionContext is run/agent context; accessRunId authorizes a history read and is distinct from sourceRunId provenance.