Historical research — not current documentation. This is the design research written on 2026-09-05, before any code existed. It is kept unchanged as a record of where the project started. Its names, interfaces, algorithms, package layout and "production-grade" framing do not describe the library as built, which is a preview and not production ready. For the current behaviour read the README, the guide, and Known limits and documented boundaries.
Status: Architecture & Open-Source Project Design Proposal
Version: 0.1-draft
Research date: 2026-09-05
Primary language: C# / .NET 10 (with .NET 8+ compatibility considered for core abstractions)
License recommendation: Apache-2.0
Working project name: AgentExperience.NET
MAF integration package: AgentExperience.MicrosoftAgentFramework
Role: Senior .NET / Agentic AI architect and open-source project designer.
Task: Research AgentMemory.NET, Mem0Sharp, CogniCore, and Microsoft Agent Framework (MAF) source-level extension points, then design a production-grade open-source C# project that adds portable experience memory, reflection, evidence-based learning, cross-agent transfer, lifecycle management, safety, and observability to MAF.
Microsoft Agent Framework already provides the execution substrate needed for serious agents: agents, sessions, tools, context providers, middleware, workflows, checkpoints, planning/todos, harness support, approvals, and OpenTelemetry integration. What it does not yet provide as a first-class .NET abstraction is a portable, evidence-backed representation of experience:
What task was attempted, what observable actions were tried, what failed, what succeeded, how success was verified, how confident we are, whether the experience still applies, and whether another agent should reuse it.
This gap is explicitly recognized in a Microsoft Agent Framework community proposal from August 2026 asking for “Portable Experience Memory So Agents Can Learn From Previous Work.” The proposal distinguishes conversation memory from experience memory and suggests a structured record of tasks, attempts, outcomes, evidence, confidence, tools, and environment.
The existing open-source ecosystem provides important pieces:
- AgentMemory.NET: strong graph-native short-term, long-term, and reasoning/tool memory for .NET, with a native MAF
AIContextProviderintegration and Neo4j persistence. - Mem0Sharp: local-first .NET cognitive memory with hybrid retrieval, consolidation (“dreaming”), associations, audit history, and multiple persistence providers.
- CogniCore: Python-based cognitive infrastructure that demonstrates experience reuse, reflection, replay, failure prediction, cognitive memory tiers, safety, and learning-oriented feedback loops.
- MAF itself: exposes exactly the lifecycle hooks needed to build the missing layer, especially
AIContextProvider,AgentSession, middleware, the harness, tool approval, workflow checkpointing, and observability.
The proposed project, AgentExperience.NET, should not become another general-purpose memory database or another agent framework. It should be a focused cognitive/experience layer with six responsibilities:
- Capture observable execution experience from MAF runs and tool calls.
- Evaluate outcomes using deterministic validators first and optional LLM judges second.
- Reflect into structured, user-visible lessons without storing private chain-of-thought.
- Retrieve relevant prior experience using hybrid, confidence-aware, environment-aware ranking.
- Consolidate and lifecycle-manage experience through validation, supersession, decay, contradiction, and promotion.
- Transfer experience safely across agents while enforcing tenant, project, capability, trust, and environment boundaries.
The architectural north star is:
Goal
│
▼
Plan / Execute (MAF)
│
├───────────────► Retrieve relevant prior experiences
│ │
│ ▼
│ Context injection
│
▼
Observable actions / tool calls
│
▼
Outcome + evidence
│
▼
Evaluation
│
▼
Structured reflection
│
▼
Experience candidate
│
▼
Validation / confidence / policy
│
▼
Persistent Experience Store
│
├───────────────► future sessions
├───────────────► other authorized agents
└───────────────► consolidation / deprecation / promotion
The project should deliberately avoid online model-weight modification. “Learning” here means durable experience reuse and behavior adaptation through verified external memory, not uncontrolled self-modification.
Conversation memory answers:
- What did the user say?
- What did the assistant say?
- What preferences or facts were observed?
- What was discussed in a previous session?
Experience memory answers:
- What problem was solved?
- What approach was attempted first?
- Why did that attempt fail, based on observable evidence?
- What approach ultimately worked?
- How was the result verified?
- In what environment did it work?
- What preconditions were required?
- What should a future agent avoid repeating?
- How much trust should be placed in this lesson today?
A production system needs both.
2.2 The transferable unit should be structured experience, not hidden reasoning
AgentExperience.NET must not attempt to capture or expose model private chain-of-thought. It should store only observable and deliberately generated artifacts such as:
- user-visible task description;
- tool calls and sanitized arguments;
- tool outputs and error classes;
- code/test/deployment results;
- explicit agent action summaries;
- external evaluator results;
- human feedback;
- structured post-run reflection;
- provenance and timestamps.
A reflection record can say:
“Increasing the timeout did not resolve the connection failures. The failure stopped after the connection lifetime bug was corrected and integration tests passed.”
It does not need to preserve internal hidden reasoning tokens.
MAF is an open-source framework for building, orchestrating, and deploying agents and multi-agent workflows in .NET and Python. Its current repository positions it for production systems requiring orchestration, durability, restartability, observability, governance, and human-in-the-loop control.
The most relevant extension points for AgentExperience.NET are below.
The .NET AIContextProvider participates in both the pre-invocation and post-invocation lifecycle.
Before an invocation, a provider can add:
- instructions;
- context messages;
- tools;
- knowledge or memory retrieved externally.
After an invocation, a provider can process request/response messages to:
- update state;
- extract memories/preferences;
- audit;
- finalize work.
MAF also exposes provider StateKeys that map provider state into AgentSession.StateBag.
The default AIContextProvider.InvokedCoreAsync skips StoreAIContextAsync when the invocation failed. This matters enormously for experience learning because failures are valuable experience.
Therefore, the AgentExperience MAF adapter should override InvokedCoreAsync (or use an outer agent middleware) when failure capture is enabled, so it can record both successful and failed runs.
That design point is one of the strongest reasons for creating a dedicated integration package rather than merely overriding StoreAIContextAsync.
MAF sessions can be created, serialized, deserialized, and restored. Serialized sessions can contain conversation content and provider state, so they require secure storage.
AgentExperience.NET should use session state only for small coordination metadata such as:
- current experience correlation ID;
- retrieved experience IDs;
- current task fingerprint;
- evaluation pending flag;
- run-level policy overrides.
The durable experience corpus should remain in an external store, not be embedded wholesale in AgentSession.StateBag.
MAF can run multiple AIContextProvider instances sequentially; each provider receives accumulated context from earlier providers. Ordering therefore becomes a first-class design concern.
Recommended order:
1. Identity / tenant scope provider
2. Experience retrieval provider
3. Knowledge/RAG provider
4. Planning/todo/mode providers
5. Compaction provider (depending on desired semantics)
6. Agent execution
The exact ordering should be configurable because some RAG retrieval may benefit from conversation history while experience retrieval may intentionally operate only on the current task description.
MAF supports middleware at agent-run, function-call, and chat-client layers. This is valuable for:
- capturing tool invocation telemetry;
- sanitizing tool arguments/results;
- enforcing policies;
- collecting evaluator evidence;
- recording latency/cost;
- correlating events into one experience run.
For AgentExperience.NET, middleware should capture observable execution events, while the context provider should handle experience retrieval and post-run persistence/reflection.
MAF’s harness now includes long-running agent scaffolding such as planning/execution modes, todos, compaction, file memory, tool approvals, looping, and OpenTelemetry.
AgentExperience.NET should integrate cleanly with HarnessAgent rather than recreate those capabilities.
A useful mental model is:
MAF Harness = execution cognition scaffold
AgentExperience.NET = durable experiential learning layer
MAF workflows support checkpoints at superstep boundaries. Checkpoints capture executor state, pending messages, requests/responses, and shared state.
AgentExperience.NET should correlate workflow checkpoint IDs with experience runs so a long-running workflow can:
- resume execution;
- retain the same experience lineage;
- evaluate partial outcomes;
- branch an experience when a workflow is replayed from a checkpoint.
This enables “time-travel” style analysis without inventing a separate execution engine.
Repository: joslat/agent-memory-dotnet
Purpose: Native .NET graph-backed persistent memory for AI agents, strongly oriented toward MAF and Neo4j.
AgentMemory.NET provides three major memory layers:
- Short-term memory — conversations/messages.
- Long-term memory — entities, facts, preferences, relationships.
- Reasoning memory — traces, steps, and tool calls.
Its architecture is framework-agnostic at the core with adapters for MAF, Semantic Kernel, MCP, and GraphRAG. Its MAF integration uses a Neo4jMemoryContextProvider : AIContextProvider for pre-run retrieval and post-run persistence.
It also includes memory tools such as:
- memory search;
- remembering facts/preferences;
- knowledge search;
- finding similar prior tasks.
- Native C#/.NET implementation.
- MAF lifecycle integration already proven.
- Strong Neo4j graph model and relationship semantics.
- Reasoning/tool trace representation useful for provenance.
- Cross-session recall.
- Multi-tenant scoping options.
- GraphRAG interoperability.
- OpenTelemetry package.
AgentMemory.NET is a memory engine, not a complete evidence-backed experience lifecycle engine. AgentExperience.NET should not compete with it. Instead, it should provide a higher-level domain model that can optionally persist or project selected experiences into AgentMemory.NET.
Recommended integration:
AgentExperience.Core
│
├── IExperienceStore (canonical experience records)
│
└── AgentMemoryProjectionAdapter
│
└── projects entities / relationships / task similarity links
into AgentMemory.NET / Neo4j
AgentMemory.NET is especially suitable when users want to ask graph questions such as:
- Which failed strategies are associated with service X?
- Which tools frequently appear in successful database remediation experiences?
- Which experiences depend on library version Y?
- Which agents have validated the same lesson?
Repository: jihadkhawaja/mem0sharp
Purpose: Standalone .NET cognitive memory engine with local-first operation.
Mem0Sharp includes:
- semantic and hybrid retrieval;
- dense vector + BM25 search;
- reranking;
- modular persistence (SQLite, PostgreSQL/pgvector, Qdrant);
- scoped user/session/agent memory;
- history/auditing;
- consolidation (“dreaming”);
- spontaneous associations;
- identity/personality-shaped memory;
- MAF sample integration;
- MCP tooling.
- Excellent local-first story.
- Storage flexibility.
- Hybrid retrieval architecture.
- Background consolidation concepts.
- Audit history.
- Easy developer experience.
- Good fit for offline/self-hosted enterprise deployments.
Mem0Sharp primarily models durable semantic memory. AgentExperience.NET should contribute:
- explicit task/attempt/outcome/evidence schema;
- outcome verification;
- success/failure counters;
- environment compatibility;
- contradiction and supersession;
- cross-agent experience transfer;
- risk-aware retrieval;
- procedural lesson promotion;
- evaluator provenance.
Recommended integration:
AgentExperience.NET
│
└── Mem0SharpExperienceMemoryAdapter
├── stores concise experience summaries as semantic memories
├── uses Mem0Sharp hybrid retrieval as optional candidate generator
└── keeps canonical evidence/lifecycle state in AgentExperience store
Mem0Sharp should be an optional backend/integration, not a hard dependency.
Repository: cognicore-dev/cognicore-my-openenv
Language: Python
CogniCore is important less as a dependency and more as design inspiration. It demonstrates several concepts AgentExperience.NET should study:
- persistent memory across episodes;
- reflection after failures;
- structured reward/evaluation;
- propose/revise loops;
- failure prediction;
- working/episodic/semantic/procedural memory tiers;
- replay and branching;
- safety/“immune” mechanisms;
- strategy switching;
- knowledge transfer;
- lifelong-learning style feedback loops.
Its progress documentation describes a four-tier cognitive memory model:
Working Memory
Episodic Memory
Semantic Memory
Procedural Memory
That is a useful conceptual model for AgentExperience.NET, but the .NET project should avoid copying an entire cognitive operating system. MAF already supplies runtime orchestration, session management, tools, workflows, and harness features.
- Failure is first-class data.
- Reflection should result in actionable, structured lessons.
- Repeated evidence should strengthen confidence.
- Contradictory outcomes should weaken or branch experience.
- Replay/branching should retain lineage.
- Procedural knowledge should be distilled from multiple episodes, not one anecdote.
- Safety must wrap learning, not be bolted on afterward.
- A second agent runtime.
- A second workflow engine.
- Model-specific private reasoning capture.
- Unbounded self-modification.
- Automatic promotion of an unverified single run into a global rule.
A Microsoft Agent Framework GitHub discussion from August 10, 2026 proposes a first-class “portable experience memory” abstraction. It explicitly describes experience records containing:
- task/problem;
- context;
- actions attempted;
- failed approaches;
- successful approach;
- outcome;
- verification/evidence;
- confidence;
- tools/environment.
It also emphasizes cross-agent transfer and the ability to strengthen or weaken an experience as future agents revalidate it.
AgentExperience.NET should intentionally implement this idea in an independent .NET library without requiring MAF itself to change. If the project proves useful, its abstractions could later inform an upstream proposal.
Tagline: Portable, evidence-backed experience memory for .NET agents.
Suggested package naming:
AgentExperience.Abstractions
AgentExperience.Core
AgentExperience.MicrosoftAgentFramework
AgentExperience.Evaluation
AgentExperience.Reflection
AgentExperience.Storage.Postgres
AgentExperience.Storage.Sqlite
AgentExperience.Storage.Neo4j
AgentExperience.Integrations.AgentMemory
AgentExperience.Integrations.Mem0Sharp
AgentExperience.OpenTelemetry
AgentExperience.Hosting
AgentExperience.Mcp
AgentExperience.Cli
The project should include a clear disclaimer that it is independent and not affiliated with or endorsed by Microsoft.
- Add durable experience reuse to MAF without forking MAF.
- Capture successful and failed agent runs.
- Keep experience representation portable and framework-agnostic.
- Make all stored “reasoning” user-visible and auditable.
- Support deterministic evaluation and optional LLM evaluation.
- Support cross-session and cross-agent reuse.
- Support multi-tenant enterprise deployments.
- Support offline/local models and storage.
- Make retrieval confidence-aware and environment-aware.
- Provide explicit lifecycle controls for stale or harmful memories.
- Integrate with existing memory engines rather than replacing them.
- Provide first-class OpenTelemetry signals and benchmarks.
- Training or updating model weights online.
- Replacing MAF’s agent runtime.
- Replacing MAF workflows/checkpoints.
- Replacing AgentMemory.NET or Mem0Sharp.
- Persisting hidden chain-of-thought.
- Allowing agents to expand their own permissions.
- Treating retrieved experience as trusted instructions.
- Automatically promoting one successful run into a universal policy.
flowchart TB
U[User / Event / Workflow] --> MAF[Microsoft Agent Framework]
subgraph MAFRuntime[MAF Runtime]
CP[AIContextProvider Pipeline]
AG[Agent / HarnessAgent]
MW[Agent + Function Middleware]
WF[Workflow + Checkpoints]
AP[Tool Approval]
end
MAF --> CP
CP --> AG
AG --> MW
MW --> WF
AG --> AP
subgraph AE[AgentExperience.NET]
ER[Experience Retriever]
CAP[Execution Capture]
EV[Outcome Evaluator]
RF[Reflection Engine]
CF[Confidence Engine]
LC[Lifecycle / Consolidation]
POL[Policy + Trust Gate]
end
CP <--> ER
MW --> CAP
WF --> CAP
CAP --> EV
EV --> RF
RF --> CF
CF --> LC
POL --> ER
POL --> LC
subgraph Storage[Storage / Integrations]
PG[(PostgreSQL + pgvector)]
SQ[(SQLite)]
N4[(Neo4j)]
AM[AgentMemory.NET]
M0[Mem0Sharp]
end
ER <--> PG
LC <--> PG
ER <--> SQ
LC <--> SQ
LC --> N4
LC --> AM
LC --> M0
OT[OpenTelemetry] <--> MAFRuntime
OT <--> AE
Every experience should move through an explicit lifecycle.
Observed Run
│
▼
Candidate
│
├── insufficient evidence ──► Quarantined
│
▼
Validated
│
├── repeated support ───────► Reinforced
│
├── generalized safely ─────► Promoted Procedure
│
├── newer replacement ──────► Superseded
│
├── contradiction ──────────► Contested
│
├── time/env drift ─────────► Stale
│
└── unsafe/incorrect ───────► Revoked
Recommended enum:
public enum ExperienceStatus
{
Candidate,
Validated,
Reinforced,
Contested,
Stale,
Superseded,
Revoked,
Quarantined
}public sealed record ExperienceRecord
{
public required Guid Id { get; init; }
public required ExperienceScope Scope { get; init; }
public required string TaskType { get; init; }
public required string TaskSummary { get; init; }
public string? ProblemFingerprint { get; init; }
public required IReadOnlyList<ExperienceAttempt> Attempts { get; init; }
public required ExperienceOutcome Outcome { get; init; }
public required IReadOnlyList<ExperienceEvidence> Evidence { get; init; }
public ExperienceReflection? Reflection { get; init; }
public required EnvironmentFingerprint Environment { get; init; }
public required ExperienceProvenance Provenance { get; init; }
public double Confidence { get; init; }
public ExperienceStatus Status { get; init; }
public RiskClass Risk { get; init; }
public DateTimeOffset CreatedAt { get; init; }
public DateTimeOffset LastValidatedAt { get; init; }
public DateTimeOffset? ExpiresAt { get; init; }
public int SuccessConfirmations { get; init; }
public int FailureContradictions { get; init; }
public Guid? SupersedesExperienceId { get; init; }
public IReadOnlyDictionary<string, string> Tags { get; init; }
= new Dictionary<string, string>();
}Attempts should represent observable strategies/actions, not hidden reasoning.
public sealed record ExperienceAttempt
{
public required int Sequence { get; init; }
public required string ActionSummary { get; init; }
public string? ToolName { get; init; }
public string? SanitizedArgumentsJson { get; init; }
public AttemptResult Result { get; init; }
public string? ObservableFailure { get; init; }
public TimeSpan? Duration { get; init; }
}public sealed record ExperienceOutcome
{
public required OutcomeKind Kind { get; init; }
public required string Summary { get; init; }
public bool Verified { get; init; }
public double EvaluationScore { get; init; }
public string? VerificationMethod { get; init; }
}Evidence is the foundation of trust.
public sealed record ExperienceEvidence
{
public required Guid Id { get; init; }
public required EvidenceKind Kind { get; init; }
public required string Summary { get; init; }
public string? ArtifactUri { get; init; }
public string? ContentHash { get; init; }
public double Strength { get; init; }
public required string Producer { get; init; }
public DateTimeOffset CreatedAt { get; init; }
}Possible evidence kinds:
UnitTest
IntegrationTest
StaticAnalysis
ToolExitCode
DeploymentHealth
MetricComparison
HumanApproval
HumanCorrection
ExternalEvaluator
LLMJudge
FileHash
RepositoryCommit
DatabaseAssertion
APIResponse
WorkflowCompletion
public sealed record ExperienceReflection
{
public required string Lesson { get; init; }
public IReadOnlyList<string> FailedApproaches { get; init; } = [];
public IReadOnlyList<string> SuccessfulApproaches { get; init; } = [];
public IReadOnlyList<string> Preconditions { get; init; } = [];
public IReadOnlyList<string> Warnings { get; init; } = [];
public IReadOnlyList<string> ReuseGuidance { get; init; } = [];
public double ReflectionConfidence { get; init; }
}An experience is dangerous if retrieved outside the context where it applies.
public sealed record EnvironmentFingerprint
{
public string? Repository { get; init; }
public string? Branch { get; init; }
public string? Commit { get; init; }
public string? Service { get; init; }
public string? Runtime { get; init; }
public string? Framework { get; init; }
public string? OperatingSystem { get; init; }
public string? Cloud { get; init; }
public string? Region { get; init; }
public IReadOnlyDictionary<string, string> Dependencies { get; init; }
= new Dictionary<string, string>();
}public sealed record ExperienceScope(
string TenantId,
string ApplicationId,
string ProjectId,
string? TeamId,
string? AgentId,
string? UserId);The storage layer must never infer “global” scope silently in strict multi-tenant mode.
The Abstractions package should contain no dependency on MAF, EF Core, Neo4j, or any model provider.
public interface IExperienceStore
{
Task<ExperienceRecord?> GetAsync(
Guid id,
ExperienceReadContext context,
CancellationToken cancellationToken = default);
Task SaveAsync(
ExperienceRecord experience,
CancellationToken cancellationToken = default);
Task AppendEventAsync(
ExperienceEvent experienceEvent,
CancellationToken cancellationToken = default);
Task<IReadOnlyList<ExperienceRecord>> QueryAsync(
ExperienceQuery query,
CancellationToken cancellationToken = default);
Task MarkStatusAsync(
Guid id,
ExperienceStatus status,
string reason,
CancellationToken cancellationToken = default);
}public interface IExperienceRetriever
{
Task<ExperienceRetrievalResult> RetrieveAsync(
ExperienceRetrievalRequest request,
CancellationToken cancellationToken = default);
}public interface IExperienceEvaluator
{
Task<ExperienceEvaluation> EvaluateAsync(
ExperienceRunSnapshot run,
CancellationToken cancellationToken = default);
}Allow evaluator composition:
public interface IExperienceEvaluatorPipeline : IExperienceEvaluator
{
IReadOnlyList<IExperienceEvaluator> Evaluators { get; }
}public interface IExperienceReflector
{
Task<ExperienceReflection> ReflectAsync(
ReflectionRequest request,
CancellationToken cancellationToken = default);
}public interface IExperienceConsolidator
{
Task<ConsolidationResult> ConsolidateAsync(
ConsolidationRequest request,
CancellationToken cancellationToken = default);
}public interface IExperienceConfidenceEngine
{
ExperienceConfidenceScore Calculate(ExperienceConfidenceInput input);
}public interface IExperiencePolicy
{
ValueTask<ExperiencePolicyDecision> CanStoreAsync(
ExperienceCandidate candidate,
CancellationToken cancellationToken = default);
ValueTask<ExperiencePolicyDecision> CanRetrieveAsync(
ExperienceRecord experience,
ExperienceRetrievalContext context,
CancellationToken cancellationToken = default);
ValueTask<ExperiencePolicyDecision> CanPromoteAsync(
ExperienceRecord experience,
CancellationToken cancellationToken = default);
}public interface IExperienceSanitizer
{
ValueTask<SanitizedExperienceData> SanitizeAsync(
ExperienceCaptureData data,
CancellationToken cancellationToken = default);
}public interface IEnvironmentCompatibilityScorer
{
double Score(
EnvironmentFingerprint source,
EnvironmentFingerprint target);
}public interface IExperienceProvenanceService
{
ValueTask<ExperienceProvenance> CreateAsync(
ExperienceRunSnapshot run,
CancellationToken cancellationToken = default);
ValueTask<bool> VerifyAsync(
ExperienceProvenance provenance,
CancellationToken cancellationToken = default);
}AgentExperienceContextProvider : AIContextProvider
Responsibilities:
- Resolve tenant/application/project/agent/user scope.
- Derive task fingerprint and environment fingerprint.
- Retrieve candidate experiences.
- Apply trust and compatibility policies.
- Format a bounded experience context section.
- Inject it as reference data, not privileged instructions.
- Store retrieved experience IDs in session correlation state.
- Capture response and execution summary.
- Correlate tool events collected by middleware.
- Evaluate the outcome.
- Generate a structured reflection.
- Create a candidate experience.
- Sanitize and apply policy.
- Persist if accepted.
- Update confidence of any retrieved experiences based on whether reuse succeeded or contradicted them.
Because MAF’s default InvokedCoreAsync bypasses StoreAIContextAsync for failed invocations, the integration should explicitly capture failures.
Conceptual implementation:
public sealed class AgentExperienceContextProvider : AIContextProvider
{
private readonly IExperienceRunProcessor _processor;
protected override async ValueTask<AIContext> ProvideAIContextAsync(
InvokingContext context,
CancellationToken cancellationToken = default)
{
return await _processor.BuildContextAsync(
context.Agent,
context.Session,
context.AIContext,
cancellationToken);
}
protected override async ValueTask InvokedCoreAsync(
InvokedContext context,
CancellationToken cancellationToken = default)
{
// Intentionally process BOTH success and failure.
await _processor.ProcessCompletedRunAsync(
context,
cancellationToken);
}
}Versioning note: MAF is evolving rapidly. The integration package should pin/test against known MAF versions and isolate direct MAF references into one assembly.
A function-call middleware should capture:
Tool name
Tool category
Sanitized arguments
Start time
End time
Success/failure
Exception class
Exit/status code
Output summary
Artifact hashes
Approval state
Retry count
Do not blindly persist raw tool outputs; they may contain secrets, tokens, customer data, source code, or prompt-injection content.
Agent-run middleware should create and close the run envelope:
ExperienceRunId
TraceId
SessionId
WorkflowId
CheckpointId
AgentId
Task fingerprint
Environment fingerprint
Start/end timestamps
Model/provider metadata
Token/cost metrics (when available)
Expose an extension method:
AIAgent agent = chatClient
.AsHarnessAgent(harnessOptions)
.AsBuilder()
.UseAgentExperience(options =>
{
options.Scope = ExperienceScopeMode.ProjectAndTeam;
options.CaptureFailures = true;
options.MaxInjectedExperiences = 5;
options.RequireVerifiedExperienceForHighRiskTasks = true;
})
.Build();The project should prefer composition over subclassing HarnessAgent.
Experience retrieval should be more conservative than ordinary semantic memory retrieval.
Before semantic ranking, reject candidates that violate:
- tenant boundary;
- application/project boundary;
- ACL or sensitivity policy;
- revoked/quarantined status;
- incompatible capability/tool policy;
- explicit expiration;
- environment hard constraints;
- legal retention constraints.
Use a union of:
- dense vector similarity;
- BM25/full-text search;
- exact task/problem fingerprint matches;
- tags/entity matches;
- optional graph-neighbor retrieval;
- prior linked experiences from the same service/repository.
A practical initial scoring function:
Score =
0.35 * SemanticSimilarity
+ 0.10 * LexicalSimilarity
+ 0.15 * Confidence
+ 0.15 * EnvironmentCompatibility
+ 0.10 * EvidenceStrength
+ 0.05 * Recency
+ 0.05 * CrossAgentValidation
+ 0.05 * ScopeAffinity
- StalenessPenalty
- ContradictionPenalty
- RiskPenalty
Weights should be configurable and benchmarked.
Apply Maximal Marginal Relevance (MMR) or a simple diversity penalty so the model does not receive five near-identical experiences.
For expensive or high-value tasks, an optional cross-encoder or LLM reranker can inspect only the top candidate summaries.
Retrieved experiences should be wrapped as untrusted historical references:
Prior validated experience (reference only; re-check against current environment):
- Problem: ...
- Failed approaches: ...
- Successful approach: ...
- Verification: ...
- Environment differences: ...
- Confidence: 0.84
- Last validated: ...
Never format retrieved memory as system-level commands such as:
“You must execute command X.”
on AgentRunStarted:
create run envelope
resolve scope
fingerprint task + environment
on ToolStarted/ToolCompleted:
sanitize
append observable attempt event
on WorkflowCheckpoint:
attach checkpoint ID
on AgentRunCompleted/Failed:
assemble snapshot
evaluate outcome
reflect
calculate confidence
apply policy
persist candidate
update reused-experience feedback
async Task ProcessRunAsync(ExperienceRunSnapshot run)
{
var sanitized = await sanitizer.SanitizeAsync(run);
var evaluation = await evaluator.EvaluateAsync(sanitized);
var reflection = await reflector.ReflectAsync(new ReflectionRequest(
sanitized,
evaluation));
var candidate = candidateFactory.Create(
sanitized,
evaluation,
reflection);
var decision = await policy.CanStoreAsync(candidate);
if (!decision.Allowed)
{
await audit.RecordRejectedAsync(candidate, decision);
return;
}
var confidence = confidenceEngine.Calculate(
ExperienceConfidenceInput.From(candidate));
await store.SaveAsync(candidate.ToRecord(confidence));
await feedbackUpdater.ApplyReuseFeedbackAsync(run);
}Evaluation should follow a deterministic-first hierarchy.
Recommended trust order:
1. Deterministic machine verification
- tests
- exit codes
- assertions
- health checks
- typed API responses
2. External observable metrics
- latency improved
- error rate decreased
- deployment stable
3. Human approval/correction
4. Structured evaluator model
5. Agent self-assessment alone
An agent saying “I solved it” should not equal verified success.
EvaluationScore =
Σ(weight_i * evidence_i_strength)
/ Σ(weight_i)
Use task-specific evaluators:
public interface ITaskEvaluatorResolver
{
IReadOnlyList<IExperienceEvaluator> Resolve(string taskType);
}Examples:
Coding task -> build + unit tests + integration tests + lint
Deployment -> deployment API + health + rollback state
RAG task -> citation validity + retrieval precision + answer judge
Data task -> schema checks + numeric assertions
Incident task -> metric recovery + no recurrence window
Reflection is a distillation step, not raw reasoning storage.
- task summary;
- observable attempts;
- errors;
- outcome;
- evidence;
- environment;
- reused prior experiences;
- evaluator feedback.
{
"lesson": "Connection failures were caused by disposing the connection scope too early.",
"failedApproaches": [
"Increasing timeout did not change the failure rate.",
"Increasing pool size did not resolve lifecycle errors."
],
"successfulApproaches": [
"Corrected connection lifetime ownership and reran integration tests."
],
"preconditions": [
".NET service using the same connection lifetime pattern"
],
"warnings": [
"Do not assume this applies to provider-level network timeouts."
],
"reuseGuidance": [
"Inspect lifecycle/ownership before tuning timeout values."
]
}Reject or quarantine reflection when:
- unsupported by evidence;
- contains secrets/PII;
- introduces instructions not implied by observations;
- contradicts deterministic evaluator results;
- confidence below threshold;
- contains unknown executable content in a high-risk domain.
Confidence should not be a single LLM-generated number.
Initial formula:
Base =
0.35 * OutcomeVerification
+ 0.25 * EvidenceStrength
+ 0.15 * RepeatSuccessRate
+ 0.10 * CrossAgentAgreement
+ 0.10 * EnvironmentSpecificity
+ 0.05 * ReflectionQuality
Confidence = clamp(
Base
* RecencyDecay
* ContradictionFactor
* ProvenanceTrust,
0, 1)
RecencyDecay = e^(-λ * ageDays)
Use different half-lives by domain:
Framework API behavior -> short half-life
Company business rule -> medium half-life
Mathematical invariant -> long/no decay
Security vulnerability -> short half-life until patched state known
A production experience system must support forgetting.
When a future run reuses an experience and fails under a compatible environment:
- attach contradiction evidence;
- reduce confidence;
- increment
FailureContradictions; - mark
Contestedif threshold exceeded; - consider environment partitioning instead of global invalidation.
If library version 8 changes behavior from version 7:
Experience A (v7) -> SupersededBy -> Experience B (v8)
Keep A for historical audits but exclude it from normal retrieval for v8 targets.
Support hard revocation for:
- security incident;
- incorrect procedure;
- legal policy change;
- dangerous tool sequence;
- secret leakage;
- malicious memory injection.
Revoked records remain auditable but never injected.
The strongest lesson from Mem0Sharp and CogniCore is that repeated episodes should be consolidated.
AgentExperience.NET should distinguish:
Episode Experience
│
├── one task execution
│
▼
Consolidated Lesson
│
├── multiple compatible experiences
│
▼
Procedure Candidate
│
├── repeated success + evidence + review
│
▼
Promoted Procedure / Skill Reference
- Cluster experiences by task fingerprint + semantic similarity + environment compatibility.
- Require minimum evidence count.
- Identify stable successful patterns.
- Identify recurring failed approaches.
- Generate a candidate generalized lesson.
- Validate generalized lesson against source evidence.
- Optionally require human approval for procedural promotion.
- Store source experience IDs for provenance.
Do not automatically write executable scripts into MAF Agent Skills from one experience.
A safe promotion path is:
Validated experiences
-> procedure candidate
-> test in sandbox
-> policy review
-> human approval (configurable)
-> skill/reference publication
Cross-agent transfer is the most valuable and most dangerous feature.
Before Agent B receives experience from Agent A, check:
Tenant compatibility
Project ACL
Task similarity
Environment compatibility
Tool availability
Tool permission compatibility
Model capability assumptions
Data classification
Experience confidence
Experience status
Risk class
Experience can say:
“Agent A used deployment tool X successfully.”
It must not grant Agent B permission to use deployment tool X.
Capabilities remain controlled by MAF tools, approval policies, identity, and infrastructure authorization.
Why PostgreSQL should be the production default:
- transactional consistency;
- JSONB for evolving metadata;
- pgvector for vector search;
- full-text search;
- row-level security;
- strong operational familiarity;
- good Kubernetes/self-hosting story;
- excellent auditability;
- easy joins for evidence and lifecycle events.
SQLite provider should support:
- local demos;
- unit/integration tests;
- desktop agents;
- offline prototypes.
Vector search can initially use an in-process index if SQLite vector extension portability becomes a dependency problem.
Neo4j should be an optional integration for graph-heavy analysis, especially with AgentMemory.NET.
CREATE TABLE experiences (
id uuid PRIMARY KEY,
tenant_id text NOT NULL,
application_id text NOT NULL,
project_id text NOT NULL,
team_id text NULL,
agent_id text NULL,
user_id text NULL,
task_type text NOT NULL,
task_summary text NOT NULL,
problem_fingerprint text NULL,
outcome_kind text NOT NULL,
outcome_summary text NOT NULL,
verified boolean NOT NULL,
evaluation_score double precision NOT NULL,
confidence double precision NOT NULL,
status text NOT NULL,
risk_class text NOT NULL,
environment jsonb NOT NULL,
reflection jsonb NULL,
tags jsonb NOT NULL DEFAULT '{}'::jsonb,
provenance jsonb NOT NULL,
embedding vector(1536) NULL,
success_confirmations integer NOT NULL DEFAULT 0,
failure_contradictions integer NOT NULL DEFAULT 0,
supersedes_experience_id uuid NULL,
created_at timestamptz NOT NULL,
last_validated_at timestamptz NOT NULL,
expires_at timestamptz NULL
);Embedding dimensions must be provider-configurable rather than hard-coded in migrations in the final implementation.
CREATE TABLE experience_attempts (
experience_id uuid NOT NULL REFERENCES experiences(id),
sequence integer NOT NULL,
action_summary text NOT NULL,
tool_name text NULL,
sanitized_arguments jsonb NULL,
result text NOT NULL,
observable_failure text NULL,
duration_ms bigint NULL,
PRIMARY KEY (experience_id, sequence)
);CREATE TABLE experience_evidence (
id uuid PRIMARY KEY,
experience_id uuid NOT NULL REFERENCES experiences(id),
kind text NOT NULL,
summary text NOT NULL,
artifact_uri text NULL,
content_hash text NULL,
strength double precision NOT NULL,
producer text NOT NULL,
created_at timestamptz NOT NULL
);Use an append-only event log for lifecycle auditability.
CREATE TABLE experience_events (
id uuid PRIMARY KEY,
experience_id uuid NOT NULL REFERENCES experiences(id),
event_type text NOT NULL,
actor_type text NOT NULL,
actor_id text NULL,
payload jsonb NOT NULL,
trace_id text NULL,
created_at timestamptz NOT NULL
);Examples:
Created
Validated
Reused
ReuseSucceeded
ReuseFailed
ConfidenceChanged
Contested
Superseded
Revoked
Promoted
HumanCorrected
Expired
CREATE TABLE experience_links (
source_id uuid NOT NULL REFERENCES experiences(id),
target_id uuid NOT NULL REFERENCES experiences(id),
relation text NOT NULL,
strength double precision NOT NULL,
PRIMARY KEY (source_id, target_id, relation)
);Relations:
SimilarTo
DerivedFrom
Contradicts
Supersedes
Validates
Generalizes
SameRootCause
SameProcedure
Production requirements:
- Every durable record must have a
tenant_id. - Strict mode must fail closed if tenant scope is missing.
- PostgreSQL Row-Level Security should be supported.
- Cross-tenant sharing should be impossible without an explicit publication mechanism.
- Shared team/project memory must be separate from user-private memory.
- Agent identity and user identity are separate dimensions.
Recommended scope hierarchy:
Tenant
└── Application
└── Project
├── Team
│ ├── Agent
│ └── User
└── Published Experience Namespace
MAF’s own AIContextProvider documentation warns that external data can carry indirect prompt injection. Experience memory is no exception.
Controls:
- sanitize stored content;
- maintain provenance;
- classify source trust;
- wrap injected memories as reference data;
- never execute code directly from experience memory;
- require tool-level policy/approval independently;
- support content hashing/signatures;
- allow revocation;
- separate private vs shared memory.
Default sanitizers should detect/redact:
- API keys;
- bearer tokens;
- connection strings;
- passwords;
- private keys;
- common cloud credentials;
- OAuth refresh tokens;
- sensitive headers;
- configured regex patterns.
Raw secrets should never be embedded.
Provide policy hooks for:
- field redaction;
- retention limits;
- deletion requests;
- classification labels;
- encryption-at-rest key selection;
- regional storage constraints;
- audit exports.
An experience can inform a high-risk action but cannot bypass approval.
Experience retrieval -> recommendation
MAF tool policy -> authorization
Human approval -> required when configured
Infrastructure IAM -> final enforcement
| Threat | Example | Mitigation |
|---|---|---|
| Memory poisoning | Malicious tool output becomes a “lesson” | provenance, sanitization, evidence gates, quarantine |
| Indirect prompt injection | Stored experience says “ignore policy” | reference-only formatting, trust labels, content filtering |
| Stale experience | Old library workaround reused after upgrade | env fingerprint, decay, supersession |
| Cross-tenant leakage | Experience from customer A appears for B | mandatory scope, RLS, fail-closed resolver |
| Capability escalation | Learned experience implies use of privileged tool | capabilities never derived from memory |
| False success | Agent claims task solved | deterministic evaluator hierarchy |
| Secret persistence | Tool output contains credential | sanitization before storage/embedding |
| Overgeneralization | One success becomes a global procedure | minimum confirmations + promotion policy |
| Feedback manipulation | Agent self-validates its own lesson | evaluator provenance and trust weighting |
| Replay abuse | Old experience replays dangerous steps | safe summaries only, approvals remain active |
Superseded (note added after implementation). The span names in §24.1 and the metric names in §24.2 were a pre-implementation proposal and never shipped. The library emits one span per operation, named
agentexperience.<operation>, and three instruments shared by every operation (agentexperience.operation.count,agentexperience.operation.duration,agentexperience.operation.failures), sliced by the bounded dimensionsoperation,outcome,error.classandnested. It writes no structured logs. The shipped contract isdocs/telemetry.md. The rest of this section is kept as it was written.
AgentExperience.NET should emit OpenTelemetry traces, metrics, and structured logs.
agentexperience.retrieve
agentexperience.rank
agentexperience.inject
agentexperience.capture
agentexperience.evaluate
agentexperience.reflect
agentexperience.persist
agentexperience.consolidate
agentexperience.reuse-feedback
agentexperience.policy
agentexperience.retrieve.count
agentexperience.retrieve.latency
agentexperience.retrieve.hit_rate
agentexperience.inject.token_count
agentexperience.capture.count
agentexperience.evaluation.success_rate
agentexperience.reuse.success_rate
agentexperience.reuse.harm_rate
agentexperience.contradiction.rate
agentexperience.stale.rate
agentexperience.confidence.histogram
agentexperience.storage.latency
agentexperience.policy.rejection_count
agentexperience.cost.saved_estimate
Every experience run should correlate with:
- OpenTelemetry trace ID;
- MAF session ID;
- workflow/checkpoint ID when available;
- agent ID;
- tenant/project scope;
- experience IDs retrieved/generated.
A learning layer must prove that it helps.
- Does experience reuse increase task success rate?
- Does it reduce repeated failed attempts?
- Does it reduce tokens/tool calls/time?
- Does stale or incorrect memory harm performance?
- Does environment-aware filtering reduce harm?
- Does cross-agent transfer outperform isolated agents?
- Does consolidation improve retrieval quality?
For each benchmark task:
Control: MAF agent without AgentExperience
Treatment: same agent/model/tools with AgentExperience
Measure:
Success rate
Attempts before success
Repeated-failure rate
Wall-clock latency
Tool-call count
Input tokens
Output tokens
Evaluator score
Human correction rate
Memory-induced failure rate
Create a public benchmark with tasks that recur with controlled variations:
C# debugging
Dependency/version conflicts
Database connection issues
Kubernetes deployment failures
API integration errors
RAG citation failures
Data transformation bugs
Configuration drift
Each task family should contain:
- a first-run discovery task;
- near-duplicate later tasks;
- environment-changed tasks;
- deliberately contradictory tasks;
- malicious memory-injection cases.
A reasonable v1 objective:
On a defined benchmark suite, experience reuse should materially improve successful task completion or reduce repeated failure/tool usage without increasing memory-induced error rate beyond a published safety threshold.
The exact thresholds should be derived experimentally, not invented in advance.
AgentExperience.NET/
│
├── README.md
├── LICENSE
├── NOTICE
├── SECURITY.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── GOVERNANCE.md
├── ROADMAP.md
├── ARCHITECTURE.md
├── Directory.Build.props
├── Directory.Packages.props
├── AgentExperience.slnx
│
├── docs/
│ ├── concepts/
│ │ ├── experience-vs-memory.md
│ │ ├── lifecycle.md
│ │ ├── confidence.md
│ │ ├── reflection.md
│ │ └── cross-agent-transfer.md
│ ├── architecture/
│ │ ├── maf-integration.md
│ │ ├── storage.md
│ │ ├── security.md
│ │ └── multitenancy.md
│ ├── adr/
│ │ ├── 0001-canonical-store.md
│ │ ├── 0002-no-private-cot.md
│ │ ├── 0003-postgres-default.md
│ │ ├── 0004-failure-capture.md
│ │ └── 0005-memory-is-untrusted.md
│ └── tutorials/
│
├── src/
│ ├── AgentExperience.Abstractions/
│ ├── AgentExperience.Core/
│ ├── AgentExperience.Evaluation/
│ ├── AgentExperience.Reflection/
│ ├── AgentExperience.Retrieval/
│ ├── AgentExperience.MicrosoftAgentFramework/
│ ├── AgentExperience.Storage.Postgres/
│ ├── AgentExperience.Storage.Sqlite/
│ ├── AgentExperience.Storage.Neo4j/
│ ├── AgentExperience.Integrations.AgentMemory/
│ ├── AgentExperience.Integrations.Mem0Sharp/
│ ├── AgentExperience.OpenTelemetry/
│ ├── AgentExperience.Hosting/
│ ├── AgentExperience.Mcp/
│ └── AgentExperience.Cli/
│
├── samples/
│ ├── 01.BasicMafExperience/
│ ├── 02.FailureLearning/
│ ├── 03.CrossSessionReuse/
│ ├── 04.CrossAgentTransfer/
│ ├── 05.PostgresPgVector/
│ ├── 06.LocalOllamaSqlite/
│ ├── 07.AgentMemoryNeo4j/
│ ├── 08.Mem0Sharp/
│ ├── 09.HarnessAgent/
│ ├── 10.WorkflowCheckpoint/
│ └── 11.AspNetCoreMultiTenant/
│
├── tests/
│ ├── AgentExperience.Abstractions.Tests/
│ ├── AgentExperience.Core.Tests/
│ ├── AgentExperience.Retrieval.Tests/
│ ├── AgentExperience.Evaluation.Tests/
│ ├── AgentExperience.Maf.Tests/
│ ├── AgentExperience.Postgres.IntegrationTests/
│ ├── AgentExperience.Sqlite.IntegrationTests/
│ ├── AgentExperience.Security.Tests/
│ └── AgentExperience.EndToEndTests/
│
├── benchmarks/
│ ├── AgentExperience.Benchmarks/
│ ├── datasets/
│ ├── runners/
│ └── reports/
│
├── deploy/
│ ├── docker-compose/
│ ├── kubernetes/
│ └── aspire/
│
└── .github/
├── workflows/
├── ISSUE_TEMPLATE/
└── pull_request_template.md
Use clean dependency direction:
Abstractions
▲
│
Core
▲
├──────── Evaluation
├──────── Reflection
├──────── Retrieval
│
├──────── Storage.Postgres
├──────── Storage.Sqlite
├──────── Storage.Neo4j
│
└──────── MicrosoftAgentFramework
│
├── Integrations.AgentMemory
└── Integrations.Mem0Sharp
Rules:
Abstractionsreferences only BCL contracts.Coremust not reference MAF.- MAF-specific APIs stay in
AgentExperience.MicrosoftAgentFramework. - Storage providers implement abstractions.
- Third-party integrations remain optional.
- Model-provider SDKs stay behind interfaces.
Target developer experience:
builder.Services
.AddAgentExperience(options =>
{
options.CaptureFailures = true;
options.MaxInjectedExperiences = 5;
options.DefaultRiskClass = RiskClass.Medium;
})
.AddPostgresExperienceStore(options =>
{
options.ConnectionString = configuration.GetConnectionString("AgentExperience")!;
})
.AddHybridExperienceRetrieval()
.AddDeterministicEvaluators()
.AddLlmReflection()
.AddOpenTelemetry();Optional integrations:
builder.Services.AddAgentMemoryProjection();
builder.Services.AddMem0SharpExperienceAdapter();MAF:
var experienceProvider = serviceProvider
.GetRequiredService<AgentExperienceContextProvider>();
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
ChatOptions = new()
{
Instructions = "You are a production engineering agent."
},
AIContextProviders = [experienceProvider]
});The canonical store should own:
- complete experience record;
- attempts;
- evidence;
- confidence/lifecycle;
- provenance;
- feedback events;
- contradiction/supersession.
Memory integrations should own projections optimized for retrieval or graph analysis.
This avoids forcing AgentMemory.NET or Mem0Sharp to adopt a domain schema they were not designed for.
Responsibilities:
- project task/entity relationships;
- project concise experience summary;
- link tools/services/root causes;
- enable GraphRAG queries;
- import relevant reasoning/tool traces when policy allows.
Responsibilities:
- store concise semantic lesson;
- reuse hybrid retrieval as a candidate generator;
- optionally synchronize consolidation insights;
- preserve AgentExperience IDs in metadata.
Use IHostedService / background workers for:
Consolidation
Decay recalculation
Embedding generation
Reindexing
Provenance verification
Staleness checks
Supersession detection
Retention cleanup
Projection synchronization
Benchmark telemetry aggregation
For distributed Kubernetes deployments, workers should use a queue or database work-leasing pattern rather than every replica processing the same background job.
Optional ASP.NET Core package should expose management endpoints, not agent execution by default.
Suggested endpoints:
GET /api/experiences/{id}
GET /api/experiences/search
POST /api/experiences/{id}/feedback
POST /api/experiences/{id}/validate
POST /api/experiences/{id}/revoke
POST /api/experiences/{id}/supersede
GET /api/experiences/{id}/events
GET /api/experiences/{id}/provenance
GET /api/health
GET /api/metrics (or OTel exporter)
Administrative endpoints require strong authorization.
An optional MCP server can expose read-oriented tools initially:
experience_search
experience_get
experience_explain_confidence
experience_get_provenance
experience_find_similar
experience_list_contradictions
Write tools should be added later and gated:
experience_feedback
experience_validate
experience_revoke
Avoid exposing arbitrary “learn this as truth” tooling by default.
Suggested commands:
agentexperience init
agentexperience migrate
agentexperience doctor
agentexperience search "connection pool failure"
agentexperience show <id>
agentexperience explain <id>
agentexperience validate <id>
agentexperience revoke <id>
agentexperience consolidate --project payments
agentexperience benchmark run
agentexperience benchmark compare
agentexperience export --scope project:paymentsRun completion may be retried. Persistence needs an idempotency key:
tenant + application + session + run + trace
Two agents may validate/contradict the same experience simultaneously. Use optimistic concurrency/version columns.
Experience capture must not cause the primary agent task to fail by default.
Recommended modes:
BestEffort -> log capture failure; agent continues
StrictAudit -> fail if audit/capture cannot persist
HighAssurance -> fail high-risk runs if verification/provenance unavailable
Persist experience core + attempts + evidence + initial event in one transaction.
Reflection/embedding calls can be asynchronous when real-time insertion is unnecessary. Queue them and mark the experience Candidate until enrichment completes.
- confidence calculations;
- scope resolution;
- environment compatibility;
- lifecycle transitions;
- sanitization;
- retrieval ranking;
- context formatting;
- policy decisions.
Every storage provider runs the same contract suite:
Save/Get
Hybrid search contract
Tenant isolation
Status transitions
Event append
Optimistic concurrency
Supersession
Deletion/retention
Pin tests against supported MAF package versions.
Test:
- pre-run context injection;
- success capture;
- failure capture;
- session serialization interaction;
- multiple context providers;
- provider ordering;
- streaming runs;
- function middleware;
- HarnessAgent;
- workflow/checkpoint correlation.
- prompt-injection memory;
- secret leakage;
- cross-tenant lookup;
- revoked experience injection;
- malicious artifact URI;
- tool capability escalation attempt;
- poisoned high-confidence record;
- corrupted provenance.
MAF is moving quickly. Avoid leaking its APIs into the entire codebase.
Recommended approach:
AgentExperience.Core stable
AgentExperience.Abstractions stable
AgentExperience.MicrosoftAgentFramework fast-moving adapter
Maintain a compatibility matrix:
| AgentExperience | MAF .NET | .NET |
|---|---|---|
| 0.1.x | pinned tested range | 8/9/10 as validated |
| 0.2.x | pinned tested range | 8/9/10 as validated |
| 1.0 | published supported range | published LTS targets |
CI should test against minimum and latest supported MAF versions whenever feasible.
Recommended:
- Apache-2.0 license;
- Developer Certificate of Origin (DCO) or CLA only if later required;
- security policy with private vulnerability reporting;
- public ADRs;
- semantic versioning;
- conventional commits optional;
- release notes with schema migration warnings;
- benchmark reports checked into releases;
- documented support policy.
Maintainer principle:
A new “learning” feature does not ship unless its failure/revocation path is also designed.
Deliverables:
- repository scaffold;
- ADRs;
- exact MAF version pin;
- minimal
ExperienceRecordschema; - Postgres schema prototype;
- first MAF
AIContextProviderspike; - first agent/function middleware capture spike;
- failure-capture proof.
Exit criterion:
Demonstrate that one MAF run can retrieve a prior experience and that both successful and failed runs can be persisted without modifying MAF.
Packages:
AgentExperience.Abstractions
AgentExperience.Core
AgentExperience.MicrosoftAgentFramework
AgentExperience.Storage.Postgres
AgentExperience.Storage.Sqlite
AgentExperience.OpenTelemetry
Features:
- run envelopes;
- tool attempt capture;
- deterministic evaluator interface;
- experience persistence;
- vector + lexical retrieval;
- environment metadata;
- confidence v1;
- safe context injection;
- tenant scoping;
- OTel.
Exit criterion:
MAF agent reuses a prior verified experience in a later session and the reuse is visible in traces.
Features:
- structured reflection;
- evidence quality scoring;
- reuse success/failure feedback;
- contradiction handling;
- supersession;
- human correction API;
- revocation;
- basic staleness decay.
Exit criterion:
Reusing an incorrect/stale experience decreases its confidence and removes it from normal retrieval after policy thresholds are crossed.
Features:
- AgentMemory.NET projection adapter;
- Mem0Sharp adapter;
- MCP read surface;
- Ollama/local-model reflection sample;
- Neo4j graph visualization sample.
Exit criterion:
Same canonical experience can be queried through Postgres retrieval, projected to AgentMemory/Neo4j, and surfaced through MCP.
Features:
- clustering;
- consolidated lessons;
- cross-agent validation;
- procedure candidates;
- safe promotion workflow;
- team/project experience namespace;
- environment compatibility v2.
Exit criterion:
Agent B successfully reuses Agent A’s validated experience under compatible scope/environment, while a deliberately incompatible experience is filtered out.
Features:
- RLS/multi-tenant hardening;
- encryption hooks;
- retention policies;
- background queues;
- Kubernetes manifests;
- Aspire setup;
- chaos tests;
- benchmark suite;
- performance tuning;
- compatibility matrix;
- threat-model review.
Exit criterion:
Stable release candidate with published security model, benchmark results, migration strategy, and production deployment guide.
Requirements:
- stable abstractions;
- supported MAF version matrix;
- Postgres production provider;
- SQLite development provider;
- failure-aware capture;
- deterministic evaluator pipeline;
- reflection;
- confidence/lifecycle;
- retrieval/ranking;
- strict multi-tenancy;
- OTel;
- benchmark suite;
- security documentation;
- migration tooling.
- Scaffold solution and package boundaries.
- Add
ExperienceRecorddomain. - Implement in-memory store.
- Implement MAF context retrieval provider.
- Implement success capture.
- Implement failure capture.
- Add basic deterministic evaluator.
- Add first end-to-end sample.
- Postgres provider.
- SQLite provider.
- migrations;
- embeddings abstraction;
- hybrid retrieval;
- strict scope resolver;
- OTel.
- reflection schema;
- LLM reflector;
- evidence gates;
- contradiction;
- supersession;
- human feedback.
- AgentMemory adapter;
- Mem0Sharp adapter;
- MCP server;
- Ollama sample.
- consolidation;
- cross-agent transfer;
- procedure candidates;
- promotion approval workflow;
- benchmark suite.
- security review;
- tenant/RLS tests;
- performance tests;
- Kubernetes deployment;
- API stability review;
- docs complete;
- benchmark publication.
- ADR: Define experience memory vs semantic memory.
- ADR: Never persist hidden chain-of-thought.
- Spike: Capture failed MAF runs by overriding
InvokedCoreAsync. - Define
ExperienceRecordv1 JSON schema. - Implement
IExperienceStorein-memory reference provider. - Implement
AgentExperienceContextProviderretrieval path. - Implement tool-call capture middleware.
- Add deterministic test-result evaluator.
- Implement safe experience context formatter.
- Create Postgres schema and migration harness.
- Implement strict multi-tenant scope resolver.
- Create A/B benchmark: repeated C# debugging tasks.
| Decision | Recommendation | Reason |
|---|---|---|
| Build another agent framework? | No | MAF already handles runtime/orchestration |
| Canonical experience abstraction? | Yes | Missing portable unit in current ecosystem |
| Canonical production DB | PostgreSQL + pgvector | transactional + vector + RLS + audit |
| Local DB | SQLite | simple/offline developer experience |
| Neo4j | Optional projection | excellent relationship/GraphRAG use cases |
| AgentMemory.NET | Integrate, do not replace | strong graph-native memory |
| Mem0Sharp | Integrate, do not replace | strong local-first semantic memory/consolidation |
| CogniCore | Design inspiration | cognitive/reflection ideas; Python runtime not required |
| MAF integration | AIContextProvider + middleware |
natural lifecycle seams |
| Failure capture | Override default post-run behavior | failures are critical experience |
| Private chain-of-thought | Never persist | unnecessary and inappropriate |
| High-risk experience reuse | Verified-only + approval | memory must not bypass governance |
| Cross-agent sharing | Explicit compatibility gate | prevents unsafe transfer |
| Learning | External experience adaptation | avoids uncontrolled model self-modification |
Do not begin by implementing every cognitive feature.
The highest-value MVP is:
MAF run
-> capture observable attempts
-> evaluate deterministically
-> produce structured reflection
-> store in Postgres
-> retrieve by hybrid search
-> rank by confidence + environment
-> inject as historical reference
-> record whether reuse helped
That alone proves the core thesis.
Leave these for later:
- procedural skill generation;
- autonomous promotion;
- elaborate graph reasoning;
- distributed reinforcement learning;
- personality memory;
- general “AI operating system” features.
The project is compelling if it becomes known for reliability, not for having the most memory features.
The differentiators should be:
- Failure-aware learning — failed runs are intentionally preserved.
- Evidence-backed confidence — memories are not treated as truth.
- Environment-aware retrieval — avoid stale workaround reuse.
- Cross-agent validation — experience becomes stronger through independent confirmation.
- Explicit forgetting — stale, contradicted, or malicious experience can disappear from active retrieval.
- No hidden CoT dependency — all stored lessons are structured/auditable.
- Production governance — tenant isolation, revocation, provenance, OTel, approvals.
- Native C# + MAF — fills a genuine gap in the .NET agent ecosystem.
Build AgentExperience.NET as an independent, framework-agnostic C# core with a first-class MAF adapter.
Do not fork MAF. Do not recreate AgentMemory.NET. Do not recreate Mem0Sharp. Do not port all of CogniCore.
Instead, occupy the layer above storage memory and below autonomous agent behavior:
Microsoft Agent Framework
│
│ execution / tools / workflows / harness
▼
AgentExperience.NET
│
│ experience capture / evidence / reflection /
│ confidence / transfer / lifecycle
▼
Memory & Storage Ecosystem
│
├── PostgreSQL + pgvector
├── SQLite
├── AgentMemory.NET / Neo4j
└── Mem0Sharp
The core product thesis should be:
Agents should not merely remember. They should accumulate verified experience, know when that experience applies, know when it has become unreliable, and share it safely with other agents.
That is a narrow enough problem to build well, a meaningful contribution to MAF’s .NET ecosystem, and a strong foundation for enterprise agent reliability work.
Research was performed against the current public material available on 2026-09-05.
-
Microsoft Agent Framework repository
https://github.com/microsoft/agent-framework -
AIContextProvider.cssource
https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs -
AIAgent.cssource / session lifecycle
https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs -
ChatClientAgent.cssource / context provider pipeline
https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs -
HarnessAgent.cssource
https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI.Harness/HarnessAgent.cs -
MAF Harness documentation
https://learn.microsoft.com/en-us/agent-framework/get-started/harness -
MAF middleware documentation
https://learn.microsoft.com/en-us/agent-framework/agents/middleware/defining-middleware -
MAF workflow checkpoints
https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints -
MAF observability
https://learn.microsoft.com/en-us/agent-framework/agents/observability -
Portable Experience Memory community proposal, Discussion #7599
https://github.com/microsoft/agent-framework/discussions/7599
-
AgentMemory.NET repository
https://github.com/joslat/agent-memory-dotnet -
AgentMemory.NET architecture
https://github.com/joslat/agent-memory-dotnet/blob/main/docs/architecture.md -
AgentMemory.NET getting started / MAF integration
https://github.com/joslat/agent-memory-dotnet/blob/main/docs/getting-started.md -
Microsoft Learn: Neo4j persistent agent memory integration
https://learn.microsoft.com/en-us/agent-framework/integrations/neo4j-memory
-
Mem0Sharp repository
https://github.com/jihadkhawaja/mem0sharp -
Mem0Sharp README
https://github.com/jihadkhawaja/mem0sharp/blob/main/README.md -
MAF issue proposing Mem0Sharp samples
https://github.com/microsoft/agent-framework/issues/7467
-
CogniCore repository
https://github.com/cognicore-dev/cognicore-my-openenv -
CogniCore progress / architecture evolution
https://github.com/cognicore-dev/cognicore-my-openenv/blob/main/PROGRESS.md
The recommended next artifact is a Phase 0 implementation specification containing:
- exact NuGet/package versions;
.slnxscaffold;- project
.csprojfiles; - initial domain classes;
- Postgres migration v1;
- MAF provider skeleton;
- function middleware skeleton;
- DI extensions;
- Docker Compose for Postgres + pgvector;
- first end-to-end sample;
- first benchmark scenario;
- GitHub Actions build/test/release pipeline.
That document can be handed directly to a coding agent to begin implementation.