Skip to content

Latest commit

 

History

History
118 lines (103 loc) · 13 KB

README.md

File metadata and controls

118 lines (103 loc) · 13 KB

AgentExperience.NET guide

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.

The learning loop, page by page

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

Glossary

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.

Design principles

  • Hexagonal core. Abstractions depends only on the BCL; Core adds 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.Redaction are 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.

What each package provides

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