These pages explain each part of the library in depth. Start with the root README for what the project is and a quick start; come here when you need the exact behaviour, the options, or the caveats. New to the library? Read Concepts in five minutes first: the whole model in one diagram. If a lesson you expected did not reach the agent, Troubleshooting is the ordered checklist for why.
AgentExperience.NET is a preview. Read Known limits and documented boundaries before you rely on any guarantee described here.
These pages describe the main branch, which the published 0.1.0-preview.19 packages match; anything added to
main after that release is listed in the changelog's Unreleased section. Code snippets use
placeholder variables (authorization, scope, hostScope, sanitizationOptions, captureLimits, logger, …)
for values you build as in the explicit wiring. The quick start
uses the one-call setup, which builds them for you.
Concepts in five minutes walks the loop end to end; these pages take one step each.
| Step | What happens | Page |
|---|---|---|
| Capture | Record what an agent tried: its attempts, tool calls, results and errors, sanitized before anything is kept | Capturing runs with MAF |
| Verify and reflect | Check the run against your own required checks, and draw a lesson that points at its evidence | Finalization |
| Store | Persist the lesson as an Experience Record, then move it through an audited lifecycle | Finalization, Lifecycle |
| Index | Optionally embed the record, after it is stored, for search by meaning | Indexing |
| Retrieve | Find the records that apply to a new task, filtered for eligibility and ranked with every weight shown, including how closely each record's environment fits | Retrieval |
| Inject | Put what survives, and what the receiving agent can act on, into its context as one labeled Historical Reference block | Injection into MAF |
| Feedback | Record what a run was given, and let only real evidence move a record's confidence | Reuse feedback, Confidence and independence |
And around the loop:
| Topic | Page |
|---|---|
| Letting another team read one record, for a bounded time, with an audit trail | Sharing and grants |
| Deleting a record, and expiring old data on your own schedule | Deletion and retention |
| Making erasure reach backups, replicas and WAL | Crypto-shredding |
| Why a lesson you expected never reached the agent | Troubleshooting |
| Wiring the services, the two database roles, and the trust boundary | Deployment |
Using the loop from any agent (a shell, or an MCP client) with the aexp tool |
CLI and MCP |
| Retrying an attempt inside one task with a corrected strategy, within budgets and only with your authorization (experimental) | Reflective execution |
Learning from Claude Code sessions through hooks, with lessons synced into CLAUDE.md or AGENTS.md |
Claude Code |
| The PostgreSQL schema, script by script, and how it is applied | PostgreSQL schema |
| What a Python or Go port must match to share lessons: the record format, the block, the task text and the search, with conformance fixtures | The language-neutral contract |
| Spans and metrics | Telemetry contract |
| The tests behind the security claims | Security suite |
| Supported versions, and the evidence for every dependency pin | Compatibility evidence |
| How a release is verified and published | RELEASING.md |
These terms have a specific meaning in this library.
| Term | Meaning |
|---|---|
| Experience Run | One attempt, or a series of retries, at one task by an agent, as the library captured it: the attempts, the tool calls with their sanitized arguments and results, errors, and the run's execution status. A run lives in memory until it is finalized. |
| Attempt | One try inside a run. With the MAF adapter, one agent invocation is one attempt. |
| Evidence | An observable fact that decides whether a check passed: an exit code, a test result, a workflow completion, a human approval. Never the model's own claim, and never hidden reasoning. |
| Verification round | A set of evidence the host closed for one artifact revision (for example, "the tests that ran against build 42"). Verification only counts evidence from the round the host closed. |
| Reflection | The lesson drawn from a verified run, with reuse guidance, preconditions and warnings. Every reflection points at the evidence IDs it rests on. |
| Experience Record | The durable, stored lesson: the run, its verification, its reflection, its scope, its lifecycle status and its reuse confidence. |
| Scope | Where a record lives: tenant, application and project (required), and optionally team, agent and user. Matching is exact; a null field is not a wildcard. (Two deliberate exceptions: a null bound on an authorization context leaves that field unrestricted, and a subtree retention sweep treats a null root field as "any".) |
| Authorization context | What the host's own authentication says the caller may touch. It always comes from the host, never from a request payload or model output. Every operation checks the scope against it first. |
| Eligible | A record in Validated or Reinforced status. Only eligible records are retrieved, injected or indexed. |
| Reuse confidence | A score in [0, 1] over independent supporting validations S and contradictions F. By default (1 + S) / (2 + S + F), strictly inside (0, 1); a host can replace the engine, and every stored score records the rule that produced it. A heuristic for ranking, not a probability. |
| Preferred environment | Environment attributes a retrieval would prefer a record to carry. Unlike required attributes, they never exclude a record; they grade its environment ranking component. |
| Domain | The value of a record's domain environment attribute (the key is configurable). An optional decay policy gives each domain its own confidence half-life at ranking time. |
| Receiving agent capabilities | What the host declares the agent about to be given lessons can do: its available tools and the highest tool risk class it may use. A lesson whose approach needs more is not injected. |
| Historical Reference | The single, delimited, labeled message the MAF adapter injects before an invocation. It carries retrieved lessons as untrusted reference material, never as instructions. |
| Exposure | The fact that the library delivered a record into a run. Confidence evidence about a run counts only for records the run was exposed to. |
| Sharing grant | An administrator's explicit, expiring permission for one other scope to read one record. |
| Tombstone | What is left of a deleted record: its ID, scope, revision and deletion time, and nothing else. The ID can never be reused. |
| Crypto-shredding | An opt-in mode where each record's text is encrypted under its own key, held outside the database. Deleting the record destroys the key, so every copy becomes unreadable. |
- Hexagonal core.
Abstractionsdepends only on the BCL;Coreadds a redaction primitive and the dependency-injection abstractions it needs to register its own services. MAF, databases, models, and telemetry stay in adapters. Dependency-boundary tests enforce this in CI. - Failure-preserving capture. Failed and cancelled runs are recorded through an outer lifecycle path, never only a success callback.
- Evidence before trust. Verification is deterministic and bound to a host-closed round and artifact revision. A completion score is never mistaken for reuse confidence.
- Sanitize before anything is stored. Unknown payload fields are dropped by default, and secrets are redacted from nested values.
- Reuse, don't rebuild. MAF middleware and
Microsoft.Extensions.Compliance.Redactionare used at the edges, and storage builds on Npgsql and pgvector rather than on a bespoke engine. Each integration was proven with executable compatibility tests before an adapter was built. - Derived data never blocks canonical data. Embeddings are produced after the commit, through a replaceable provider port, and every failure leaves the record committed, text-searchable, and retryable.
- Hidden reasoning is never stored. The library records observable evidence (tool calls, results, errors, verification checks) and never chain-of-thought.
| Capability | Package |
|---|---|
| Domain contracts: experience runs, attempts, evidence, outcomes, reflections, scope, environment, and every port | AgentExperience.Abstractions |
| Sanitization before storage: per-kind allowlists, secret redaction, fail-closed rejection | AgentExperience.Core |
| Thread-safe in-memory run capture with idempotent appends and size limits | AgentExperience.Core |
| Deterministic task verification: exit codes, tests, workflow and human checks; host-closed rounds; no LLM | AgentExperience.Core |
| Auditable, template-based reflections traceable to evidence IDs | AgentExperience.Core |
| One finalization call: evaluate, gate on authorization and the host's storage decision, reflect, create the record, commit its first lifecycle event — replay-safe | AgentExperience.Core |
| The audited lifecycle transition table, with supersession and database-enforced append-only logs | AgentExperience.Core, AgentExperience.Storage.Postgres |
| Evidence-based reuse confidence with verified, exposure-bound independence, computed by a replaceable engine | AgentExperience.Core, AgentExperience.Storage.Postgres |
| Reuse feedback that records exposure and lets only established evidence move a score | AgentExperience.Core, AgentExperience.Storage.Postgres |
| Text retrieval and hybrid (text plus vector) retrieval, bounded by a timeout, with explainable ranking, graded environment fit and optional per-domain confidence decay | AgentExperience.Core, AgentExperience.Storage.Postgres, AgentExperience.Storage.Postgres.Vectors |
| Embedding ingestion after the canonical commit, conditional on the record's revision | AgentExperience.Core, AgentExperience.Storage.Postgres.Vectors |
| MAF adapter: capture of ordinary, streaming, failed and cancelled runs and their tool calls, retries as attempts of one run, and Historical Reference injection with session tracking and a gate on the receiving agent's tools and risk class | AgentExperience.MicrosoftAgentFramework |
| Sharing grants with a bounded lifetime, disclosure levels, and an optional access log | AgentExperience.Abstractions, AgentExperience.Storage.Postgres |
| Deletion, retention sweeps and purges, with append-only guards that are never disabled | AgentExperience.Storage.Postgres, AgentExperience.Storage.Postgres.Vectors |
| Opt-in crypto-shredding with an envelope key store for any KMS | AgentExperience.Abstractions, AgentExperience.Core, AgentExperience.Storage.Postgres, AgentExperience.Storage.Postgres.Vectors |
| A supported two-role PostgreSQL deployment, with privileges applied and verified on every deploy | AgentExperience.Storage.Postgres |
| Journaled schema migrations, one transaction per script, serialized across processes | AgentExperience.Storage.Postgres, AgentExperience.Storage.Postgres.Vectors |
OpenTelemetry-compatible spans and metrics through the BCL's ActivitySource and Meter |
AgentExperience.Core, AgentExperience.MicrosoftAgentFramework, AgentExperience.Storage.Postgres |
| In-memory record store, candidate source and reuse-feedback store, for development and tests only: data is lost when the process ends, none of the PostgreSQL guarantees apply, search matches every query word but does not stem, with relevance values unlike PostgreSQL's, and the registration refuses any environment but Development, Test or Testing unless overridden. Passes the same store conformance suite as PostgreSQL | AgentExperience.Storage.InMemory |
Dependency-injection registration for each package; every registration uses TryAdd, so your own implementation wins |
all but AgentExperience.Abstractions |
The one-call setup, services.AddAgentExperience(...) with .UseInMemoryStorageForDevelopment() or .UsePostgres(...), and UseAgentExperience on the agent builder |
AgentExperience.MicrosoftAgentFramework, with AgentExperience.Storage.InMemory or AgentExperience.Storage.Postgres |