MemoryPromotionService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-13 Promoted Memory
Platform / plane	Knowledge Platform / Knowledge & Memory
Deployment granularity	module of host · host KnowledgeHost
Status	target · ConnectSoft.Factory.Knowledge.Memory
Built from	connectsoft-microservice · libraries: connectsoft-extensions-ai, connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate
Decisions	ADR-0014, ADR-0019, ADR-0021
Traceability	FR-07 FR-08 FUX-09 FUX-10 NFR-03 NFR-11 NFR-16 XL-08 XL-14

Purpose and responsibilities

Knowledge is what the organization knows; memory is what happened and what was learned (original handoff §26). Working memory is run state (BC-03, BC-06) and is not stored here. MemoryPromotionService owns the other classes: episodic memory (run 8742 upgraded BillingService, package X v9 failed, v8.4 worked, PR 892), semantic candidates (facts learned from execution) and procedural candidates (how work is done, which evolve into versioned skills). It runs the lifecycle of §31: observation → candidate → classification → evidence check → confidence → policy → store → reinforce or decay → archive or delete, and it prevents uncontrolled accumulation of low-quality generated memory.

This service was added by the design plan because BC-13 had no module row; the June-2026 rows PromptMemoryService, RuntimeMemoryService and DecisionMemoryService stay later-stage.

Context and boundaries

flowchart LR
    S["MemoryPromotionService"]
    ContextBuilderService["ContextBuilderService"] -->|grpc| S
    AgentRuntimeService["AgentRuntimeService"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| RunControlService["RunControlService"]
    S -->|grpc| ModelRouterService["ModelRouterService"]
    S -->|grpc| VectorMemoryService["VectorMemoryService"]
    S -->|grpc| ArtifactService["ArtifactService"]
    S -->|grpc| AgentRegistryService["AgentRegistryService"]
    S -->|grpc| PolicyEngineService["PolicyEngineService"]
    S -. "MemoryObserved" .-> E_MemoryObserved(("event"))
    S -. "MemoryClassified" .-> E_MemoryClassified(("event"))
    S -. "MemoryPromoted" .-> E_MemoryPromoted(("event"))
    S -. "MemoryArchived" .-> E_MemoryArchived(("event"))
    S -. "SkillCandidateProposed" .-> E_SkillCandidateProposed(("event"))

Hold "Alt" / "Option" to enable pan & zoom

Governance (D32, D33): learning is tenant-scoped; promotion to Shared scope needs a reviewed proposal and the tenant's consent record; promotion of a semantic memory is an approval-gated action of class publication bound to the memory's content hash (D21), requested through Run Control and decided by a Reviewer or Workspace admin.

Domain model

MemoryItem — One memory from observation to promotion — class, scope, provenance (run, attempt, artifacts, sources), evidence verdict, confidence, review decision, reinforcement count, decay and expiry. (catalog entry)

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
projectId	string	no
scope	enum:MemoryScope	yes
class	enum:MemoryClass	yes
state	enum:MemoryState	yes
summaryRef	string	yes	Artifact reference of the memory text (content never in the row).
originRunId	guid	yes
originAttemptId	guid	no
evidenceRefs	list:string	yes	Artifacts, receipts and source citations supporting the memory.
confidence	decimal	yes
trustTier	string	yes	AgentObservation until promoted; InferredFact or SourceFact after evidence check.
reviewApprovalId	guid	no	Approval of class publication (memory promotion is a gated action, D21).
reinforcements	int	yes
lastUsedAt	datetime	no
expiresAt	datetime	no
promotedAt	datetime	no
version	long	yes

Invariants:

• A memory reaches Promoted only through a review decision bound to its exact content hash (approval of class publication); Shared scope additionally requires the tenant's consent record.
• Semantic candidates become organizational facts only with an evidence verdict that cites sources; otherwise they stay AgentObservation and are retrievable only as such.
• Procedural candidates that are reinforced beyond the threshold are proposed as skill releases (BC-04), not promoted as memory.
• Every memory has an expiry; reinforcement extends it, decay archives it; deletion follows the project's data lifecycle (D31).

stateDiagram-v2
    Observed --> Candidate : ObservationAccepted
    Candidate --> Classified : Classify
    Classified --> Deleted : ClassDiscardOrTemporaryExpired
    Classified --> EvidenceChecked : EvidenceCheck
    EvidenceChecked --> InReview : PolicyRequiresReview
    EvidenceChecked --> Promoted : PolicyAutoPromote
    InReview --> Promoted : ReviewApproved
    InReview --> Archived : ReviewRejected
    Promoted --> Reinforced : UsedSuccessfully
    Reinforced --> Promoted : ReinforcementRecorded
    Promoted --> Decayed : UnusedPastWindow
    Decayed --> Archived : Archive
    Archived --> Deleted : RetentionPassed

Hold "Alt" / "Option" to enable pan & zoom

Events: MemoryObserved, MemoryClassified, MemoryPromoted, MemoryArchived, SkillCandidateProposed · Tables: MemoryItems, ReviewDecisions, ConsentRecords · Repository: MemoryItemRepository

erDiagram
    MemoryItem {
        guid memoryId PK
        string tenantId
        string projectId
        enum_MemoryScope scope
        enum_MemoryClass class
        enum_MemoryState state
        string summaryRef
        guid originRunId
        guid originAttemptId
        list_string evidenceRefs
        decimal confidence
        string trustTier
        guid reviewApprovalId
        int reinforcements
        datetime lastUsedAt
        datetime expiresAt
        datetime promotedAt
        long version
    }
    ReviewDecision {
        guid decisionId

        guid approvalId

        hash contentHash

        string decidedBy

        datetime decidedAt

        string outcome

        string reason

    }
    MemoryItem ||--o{ ReviewDecision : contains

Hold "Alt" / "Option" to enable pan & zoom

stateDiagram-v2
    [*] --> Observed
    Observed --> Candidate
    Candidate --> Classified: temporary, episodic, semantic candidate, procedural candidate, discard
    Classified --> Deleted: discard or temporary expired
    Classified --> EvidenceChecked
    EvidenceChecked --> InReview: policy requires review
    EvidenceChecked --> Promoted: episodic auto-promotion in run or project scope
    InReview --> Promoted: review approved
    InReview --> Archived: review rejected
    Promoted --> Reinforced: used successfully
    Reinforced --> Promoted
    Promoted --> Decayed: unused past the window
    Decayed --> Archived
    Archived --> Deleted: retention passed
    Deleted --> [*]

Hold "Alt" / "Option" to enable pan & zoom

Entities and value objects

ReviewDecision (entity, in MemoryItem) — A reviewer's decision on promotion bound to the memory's content hash.

Field	Type	Required	Description
decisionId	guid	yes
approvalId	guid	yes
contentHash	hash	yes
decidedBy	string	yes
decidedAt	datetime	yes
outcome	string	yes	approved
reason	string	no

Data model and storage

Store	Role	Engine / profile	Tables
Knowledge metadata store	primary	azure-sql / nhibernate-sqlserver	MemoryItems, ReviewDecisions, ConsentRecords
Artifact content store	blob	blob / azure-blob	—

Table	Owner	Columns	Indexes
dbo.MemoryItems	MemoryItem	19	2
dbo.ReviewDecisions	ReviewDecision	9	0
dbo.ConsentRecords	MemoryItem	5	0

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/memory	ListMemory	factory.memory.read	read	natural	GW-03	Memories in scope by class, state and trust tier with provenance.
GET	/factory/memory/{memoryId}	GetMemory	factory.memory.read	read	natural	GW-03	A memory with its evidence, review decisions and usage.
POST	/factory/memory/{memoryId}/promote	PromoteMemory	factory.memory.review	publication	natural	GW-03	Promote a reviewed candidate (approval-gated action of class publication bound to the content hash).
POST	/factory/memory/{memoryId}/archive	ArchiveMemory	factory.memory.review	shared-write	natural	GW-03	Archive a memory (reviewer or workspace admin).
PUT	/factory/memory/consent	SetMemoryConsent	factory.memory.admin	production	natural	GW-03	Grant or revoke the tenant's consent for Shared memory and cross-tenant patterns (Platform admin).

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Memory	RetrieveMemory	none	internal	read	Promoted memories in scope ranked for a task; used by context assembly (episodic and semantic sections).
Memory	Observe	none	internal	shared-write	Submit observations from a completed attempt or run as candidate memories.

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
MemoryObserved	memory.items.v1.memory-observed	integration / 1	MemoryItem	DashboardService	An observation became a candidate.
MemoryClassified	memory.items.v1.memory-classified	integration / 1	MemoryItem	StudioBff, DashboardService	A candidate was classified and evidence-checked.
MemoryPromoted	memory.items.v1.memory-promoted	integration / 1	MemoryItem	ContextBuilderService, StudioBff, AuditService	A memory is retrievable in its scope after review.
MemoryArchived	memory.items.v1.memory-archived	integration / 1	MemoryItem	ContextBuilderService, DashboardService	A memory was archived (rejected, decayed or expired).
SkillCandidateProposed	memory.items.v1.skill-candidate-proposed	integration / 1	MemoryItem	FeedbackService, StudioBff, StudioNotificationService, AuditService	A reinforced procedural memory is proposed as a skill release for Asset maintainers.

MemoryObserved payload:

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
projectId	string	no
originRunId	guid	yes

MemoryClassified payload:

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
class	enum:MemoryClass	yes
confidence	decimal	yes
trustTier	string	yes

MemoryPromoted payload:

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
scope	enum:MemoryScope	yes
class	enum:MemoryClass	yes
reviewApprovalId	guid	no

MemoryArchived payload:

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
reason	string	yes

SkillCandidateProposed payload:

Field	Type	Required	Description
memoryId	guid	yes
tenantId	string	yes
proposalRef	string	yes

Command	Handled by	Result events	Summary
Observe	MemoryItem	MemoryObserved
PromoteMemory	MemoryItem	MemoryPromoted
ArchiveMemory	MemoryItem	MemoryArchived

Event	Producer	Handler	Purpose
RunCompleted	RunControlService	CollectObservations	Collect episodic observations and candidate facts from a completed run (learning loop §32).
AttemptOutcomeReported	AgentRuntimeService	CollectAttemptObservations	Collect per-attempt observations (problems, resolutions, tool outcomes).
ApprovalDecided	RunControlService	ApplyReviewDecision	Promote or archive after the review approval.
ArtifactStored	ArtifactService	LinkEvidence	Link evidence artifacts to candidate memories.
SourceDeleted	KnowledgeIngestionService	InvalidateEvidence	Re-check memories whose evidence cited a deleted source.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
Classifier	event	MemoryClassified	exponential	memoryId + classifierVersion	Classifies candidates (structured profile) into temporary, episodic, semantic candidate, procedural candidate or discard with a confidence; never promotes.
EvidenceChecker	event	—	exponential	memoryId + evidenceVersion	Checks semantic candidates against sources and receipts, sets the trust tier and routes to review per policy.
DecaySweeper	schedule 0 5 * * *	MemoryArchived, SkillCandidateProposed	fixed	memoryId + day	Decays unused memories past their window, archives decayed ones and proposes reinforced procedural memories as skill candidates.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

sequenceDiagram
    participant RC as RunControlService
    participant M as MemoryPromotionService
    participant R as VectorMemoryService
    participant Rev as Reviewer
    RC-)M: RunCompleted
    M->>M: observations become candidates, Classifier runs
    M->>R: evidence retrieval against sources
    M->>M: trust tier set, policy consulted
    M->>RC: RequestApproval class publication bound to content hash
    Rev->>RC: decision approve
    RC-)M: ApprovalDecided
    M->>M: Promoted, MemoryPromoted

Hold "Alt" / "Option" to enable pan & zoom

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Knowledge:Memory	ClassifierProfile	string	structured	yes	no	Model profile for classification.
Knowledge:Memory	AutoPromoteEpisodic	bool	true	yes	no	Episodic memories of Run and Project scope promote without review; semantic and Shared never do.
Knowledge:Memory	DecayDays	int	90	yes	no	Unused window before decay.
Knowledge:Memory	SkillProposalThreshold	int	5	yes	no	Reinforcements before a procedural memory is proposed as a skill.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.memory.items	updown	{memory}	tenant, class, state, scope	Memories by class, state and scope.
connectsoft.factory.memory.promotions	counter	{memory}	tenant, class, reviewed	Promotions, reviewed or auto.
connectsoft.factory.memory.in_review	updown	{memory}	tenant	Candidates waiting for review.
connectsoft.factory.memory.skill_candidates	counter	{proposal}	tenant	Skill proposals from procedural memory.

Security

Authentication	client-credentials
Scopes	factory.memory.read (Read memories in scope.); factory.memory.review (Promote or archive (Reviewer, Workspace admin).); factory.memory.admin (Tenant consent (Platform admin).)
Roles	Requester, Reviewer, AssetMaintainer, WorkspaceAdmin, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	publication
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
RunControlService	grpc	RequestApproval for promotion (class publication).	fail-fast	yes
ModelRouterService	grpc	Classification and evidence summaries through profiles.	degrade	yes
VectorMemoryService	grpc	Evidence retrieval against sources.	degrade	yes
ArtifactService	grpc	Memory text and proposal artifacts by hash.	fail-fast	yes
AgentRegistryService	grpc	Skill candidate proposals as Draft releases.	degrade	no
PolicyEngineService	grpc	Promotion policy (review required, scope allowed).	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
ContextBuilderService	grpc	RetrieveMemory.	—	yes
AgentRuntimeService	grpc	Observe.	—	yes
StudioBff	sync-http	Memory review views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Classifier unavailable	Classifier worker failures	candidates wait in Candidate; nothing is promoted	none	60
Evidence source deleted	SourceDeleted referencing evidence	memory re-checked; if evidence is gone it is demoted to AgentObservation or archived	none	0
Review backlog	in_review above threshold	alert to reviewers; candidates remain retrievable only as observations	none	0

NFR targets

Target	Class value (pilot-batch)	Override
latency_p95_ms	0	—
availability_pct	99.5	—
throughput_rps	10	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	medium	—

Deployment

Granularity	module of host · host KnowledgeHost
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	—; replicas —–—
Ports	—

Current implementation

Only in-memory chat history exists in the agents framework; no memory class, lifecycle, review or consent exists. The runtime memory page describes the earlier generation's feedback loop that this service governs.

Later capabilities

Governed cross-tenant pattern sharing with anonymisation (consent kind cross-tenant-pattern); prompt memory and decision memory classes; memory quality scoring from downstream run outcomes.

Decisions and traceability

Family	Ids
FR	FR-07, FR-08
FUX	FUX-09, FUX-10
NFR	NFR-03, NFR-11, NFR-16
XL	XL-08, XL-14

Related

• Runtime memory · Knowledge governance · Quality gates · Approvals

• Knowledge Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map