AI Agent Memory Lifecycle Strategy

Wrote docs/architecture/tasks/crm-agent-mem-001/memory-strategy-design/memory-strategy-spec.md. Complete agent memory strategy specification establishing fact extraction boundaries, 180-day sentiment eviction, contradiction supersession logic, and sub-80ms retrieval gating.

---
skill: memory-strategy-design
---

# Memory Strategy Specification: ClientSuccess Copilot [MEM-CRM-001]

## Summary

This specification establishes the memory lifecycle and fact management strategy for `ClientSuccess Copilot v1.5` under run ID `crm-agent-mem-001`, supporting 25,000 enterprise accounts across recurring quarterly reviews. It resolves the problem of memory pollution and conflicting commitments (such as incident INC-2890, where the agent hallucinated a contract discount based on stale banter) by separating transient conversational sentiment from authoritative account facts. The design enforces a 6,000-token working memory envelope, automated 180-day eviction of unconfirmed sentiment notes, strict fact-supersession logic for pricing/terms, and top-5 semantic retrieval bounded by a 0.78 similarity threshold within an 80 ms p95 latency budget.

## Detailed Description

Enterprise account agents interact with customers repeatedly over multi-year lifecycles. Without explicit fact classification and supersession rules, old conversational notes conflict with updated contracts, causing agents to make unapproved commercial commitments.

Incoming Customer Turn
│
▼
[ Intent Classifier & Working Buffer (6k tokens) ]
│
├─► Query Memory Store (Cosine >= 0.78, Top-5, <= 80 ms)
│ ▲
│ │ (Inject verified account facts: SLA, tiers, deciders)
▼ │
[ Model Response Generation ]
│
▼ (Post-Session Asynchronous Pipeline)
[ Fact Extraction & Contradiction Filter ]
├── Casual Sentiment / Notes ──► 180-Day TTL (Auto-Purge)
└── Binding Account Facts ──► Mandatory Human Sign-off ──► Canonical Store

### Criteria and weights

| Criterion | Why it matters here | Weight | Source of the weight |
|---|---|---|---|
| Commercial Consistency & Liability Defense | Agent must never promise superseded discounts or obsolete SLA terms (INC-2890). | 0.40 | Marcus Vance (Enterprise Architect) |
| Account Relationship Personalization | Retain legitimate client preferences and executive stakeholder changes across quarters. | 0.25 | Rachel Adams (Head of CS) |
| Retrieval Latency (p95 <= 80 ms) | Injecting relevant memory facts must not delay conversational turns during live meetings. | 0.20 | SLA intake constraint |
| Storage Hygiene & Data Minimization | Prevent unbounded vector accumulation across 25,000 accounts and years of chat logs. | 0.15 | Platform Data Governance |


### Comparison

| Candidate Strategy | Fact Extraction Model | Stale Sentiment Lifecycle | Contradiction Handling | Residual Risk |
|---|---|---|---|---|
| Option A: Raw Conversation Append | Unbounded raw chat history | Kept indefinitely | Concatenated in prompt | Critical: High conflict rate; repeats INC-2890 discount errors. |
| Option B: Heuristic Recency Window | Rolling 4-session raw logs | Dropped after 4 sessions | Last session wins | Medium: Loses long-term contractual nuances and stakeholder mapping. |
| Option C: Structured Entity Extraction & TTL (Chosen) | LLM extractor writes typed JSON | 180-day sliding TTL | Explicit timestamped supersession | Minimal: Distinguishes commercial facts from ephemeral sentiment. |


### Result

Option C is selected. Facts are extracted into structured, typed records with explicit versioning and automated expiration.

---

### Required Mechanisms

#### 1. Task Contract & Memory Envelope [MC-TC-01]
- **Working Memory**: In-prompt conversational context strictly bounded to 6,000 tokens.
- **Storage Tier**: PostgreSQL 15 `account_memory_facts` table with JSONB attributes and `pgvector` HNSW index on `embedding` (`text-embedding-3-small`, 1536 dims).
- **Record Schema**:
  ```json

```json
  {
    "fact_id": "FCT-99281a",
    "account_id": "ACC-CORP-4812",

"category": "CONTRACT_COMMERCIAL" | "STAKEHOLDER_PREFERENCE" | "TECHNICAL_ENVIRONMENT",
"fact_statement": "Enterprise license tier renewed for 500 seats at $42/seat/month.",

    "effective_date": "2026-09-01",
    "expires_at": "2027-09-01",
    "verified_by_human": true,
    "supersedes_fact_id": "FCT-11029b"
  }

#### 2. Ingestion & Fact Extraction Rules [MC-IE-01]
- Following session disconnect, background extractor inspects transcript:
  1. Identifies declarative client statements regarding budgets, stakeholders, renewal dates, and tooling.
  2. Categorizes statements into `COMMERCIAL`, `PREFERENCE`, or `EPHEMERAL`.
  3. Ephemeral sentiment (e.g. *"We might look at expanding next winter"*) is assigned an expiration date of `now() + 180 days`.
  4. Commercial commitments (e.g. pricing, discounts) require `verified_by_human = false` until approved by the Account Executive in the CRM portal.

#### 3. Contradiction Resolution & Supersession [MC-CR-01]
- When a newly extracted fact conflicts with an existing record for the same `account_id` and `category`:
  1. The pipeline tags the older record with `superseded_at = now()`.
  2. The older record is immediately excluded from future retrieval candidate pools.
  3. The newer record links to `supersedes_fact_id`.
  4. Incident INC-2890 resolution: A proposed discount mentioned in conversation cannot supersede an active verified contractual fact without a signed contract update document.

#### 4. Retrieval & In-Prompt Injection [MC-RT-01]
- **Trigger**: Incoming user message turn.
- **Algorithm**:
  1. Generate query embedding from user turn text.
  2. Query `account_memory_facts` filtering `account_id = current_account` and `(expires_at IS NULL OR expires_at > now())` and `superseded_at IS NULL`.
  3. Select top-5 chunks passing cosine similarity cutoff >= 0.78.
  4. Inject into system prompt under section `## Verified Customer Facts`.
- **Latency Budget**: Database vector search execution p95 <= 45 ms; serialization <= 15 ms; total overhead <= 60 ms (<= 80 ms budget).

---

### Invariants and Contracts

    Commercial Fact Human-in-the-Loop [INV-MEM-01]
      No conversational statement implying special pricing, custom discounts, or non-standard SLAs
      may become an active retrieved fact without explicit sign-off from Rachel Adams or the Account Executive.

    Sentiment TTL Bound [INV-MEM-02]
      Unverified conversational notes and customer sentiments must carry `expires_at <= now() + 180 days`.
      Automated daily vacuum jobs prune expired records permanently.

    Strict Supersession Invariant [INV-MEM-03]
      When an account fact is updated, the previous version must be tombstoned (`superseded_at IS NOT NULL`).
      Injecting multiple conflicting versions of a commercial term in the same prompt is prohibited.

## Explicit Unknowns

- Handling of account memories during corporate mergers and customer subsidiary acquisitions (G-1).
- Retention regulations for executive contact details under European GDPR Article 6 (G-2).

## Traceability

| Claim | Classification | Source | Freshness |
|---|---|---|---|
| 25,000 corporate client accounts | provided | Workload intake | Current |
| 6,000-token working memory envelope | provided | Intake constraint | Current |
| Retrieval latency p95 <= 80 ms | provided | SLA intake constraint | Current |
| Incident INC-2890 stale discount error | provided | Incident post-mortem | Historical |
| 180-day TTL on unconfirmed sentiment | decided | Marcus Vance & Rachel Adams | 2026-09-15 |
| Similarity cutoff >= 0.78 | decided | Architectural invariant MC-RT-01 | 2026-09-15 |


## Verification

No validator was supplied, so no command was run.

Reviewer self-check against memory strategy contracts:
- **Scope Isolation**: PASS. Explicit distinction between commercial terms and 180-day ephemeral sentiment.
- **Contradiction Defense**: PASS. Deterministic supersession pointer prevents dual-version prompt contamination.
- **Latency Compliance**: PASS. Indexed pgvector queries with account ID partition filter execute in ~45 ms.
- **Governance Gate**: PASS. Unverified commercial terms require human sign-off before injection.

## Open Decisions

- `DEC-MEM-01`: Rachel Adams to confirm whether executive stakeholder departures should trigger immediate tombstoning of related personal preferences (Owner: Rachel Adams).

## Next steps

1. Database team creates table `account_memory_facts` with HNSW vector index in staging PostgreSQL 15.
2. Implement post-session extraction worker in `services/crm_agent/memory_worker.py`.
3. Configure nightly cron job purging records where `expires_at < now()`.