# Theo · Memory (MCIR 2.0)

> MCIR (Memory Context & Intent Response) is Theo's memory protocol. It runs in front of every response generator and rewrites prompts with intent-driven memory context drawn from four typed layers before the target model sees the request. MCIR 2.0 adds the Memory Chain layer for conversation-level synthesis and proactive open-loop tracking.

Source of truth: https://hitheo.ai/protocol and https://hitheo.ai/memory. Last updated: 2026-05-24.

## At a glance
- 8 protocol stages: Capture, Classify, Index, Retrieve, Validate, Apply, Expire, Audit.
- 4 memory layers: episodic, semantic, procedural, chain.
- 5 durability rails: Bayesian shrinkage; per-model attribution; hard floor on user-declared facts; versioned replayable scoring; decay on everything.
- 0 training on customer memory. By design.
- 5 new MCIR 2.0 tables: memory_chains, open_loops, agent_meta_memories, memory_outcome_events, mcir_score_snapshots.

## MCIR-base pipeline (runs before every response)
1. Intent resolution. Every turn is parsed into a structured TaskIntent (verb, object, modifiers, temporal scope, target artifact, confidence). Canonical verbs hit a sub-1 ms regex fast path; everything else falls back to a structured-JSON classifier (~300 ms). Temporal cues ("yesterday", "earlier today") resolve to concrete ISO windows.
2. Memory context assembly. Retrieval is intent-scoped, not keyword-scoped. The assembler walks four layers and pulls only the fragments the resolved verb needs. Fragments are provenance-tagged (memoryId / messageId / artifactId / conversationId / createdAt), ranked by salience, and capped at 16 per turn.
3. Context fusion. The fuser produces a structured MCIREnvelope: originalPrompt, intent, ranked memoryFragments[], reconstructedPrompt (original prompt plus minimal [ref: …] / [when: …] anchors), and a natural-language systemBlock for models that have not been trained on the protocol natively.
4. Response generation. The orchestrator swaps the original prompt for the reconstructedPrompt, appends the systemBlock to skill prompt extensions, and dispatches to the appropriate engine. Same envelope, any qualified routing target, with full failover and per-provider circuit breaker.

## The public 8-stage protocol
1. Capture. Every interaction surfaces facts, preferences, decisions, and unresolved questions, captured the moment they happen, without manual tagging.
2. Classify. Each memory lands on the right shelf (user preference, business rule, task, relationship, risk signal, compliance note). Never one-bucket-fits-all.
3. Index. Memory is scoped to the right owner (user, account, organization, workflow) with row-level tenant isolation.
4. Retrieve. Only memories relevant to the current task surface. Intent-scoped retrieval beats keyword search.
5. Validate. Stale or contradicted entries are flagged before they touch a response.
6. Apply. Memories are applied with provenance: as facts, preferences, warnings, or instructions. Never blended into a soup.
7. Expire. Bayesian decay, revalidation windows, hard floors on user-declared facts.
8. Audit. Every retrieve, use, ignore, create, and update is logged with hash-anchored provenance.

## Four memory layers
- Episodic. Conversation turns + the artifacts they produced. Timeline-indexed so "the PDF from last week" resolves to a real range.
- Semantic. Distilled facts about customers, accounts, business. Source-tagged, confidence-scored, freshness-aware. Auto-promoted when the same entity appears in two or more chains.
- Procedural. Learned workflows + business rules. Repeated patterns are promoted into durable procedural memory.
- Memory Chain. Conversation-level synthesis: { kind, title, summary, entities, outcome }. Open loops + agent meta-memories ride here.

## MCIR 2.0 / Memory Chain layer
A conversation-level synthesis layer that compresses each conversation into a compact memory token and surfaces relevant prior tokens proactively in new threads.

Memory token shape:
```
{
  kind:    "quest" | "task" | "qa" | "service" | "search",
  title:   "<= 120 chars",
  summary: "<= 800 chars",
  entities: [{ kind, value }, ...],
  outcome: "resolved" | "partial" | "open" | "abandoned"
}
```

Synthesizer trigger: debounced. Burst threshold (3 turns → immediate enqueue with 60s lock) or 5-min idle window. Worker loads last 40 turns, makes one structured-JSON call, then upserts chains / loops / meta and promotes repeat entities to atomic memories.

## Recall scoring
```
score = entityOverlap × recencyMultiplier × effectiveSalience × kindBoost

  entityOverlap     ∈ [0, 1], normalized so 20-entity chains aren't unfairly favored
  recencyMultiplier exp decay with 14-day half-life
  effectiveSalience 0.7 × salience_base + 0.3 × salience_learned[currentModelId], clamped to [0, 1]
  kindBoost         1.2× when intent verb prefers chain kind, else 1.0
  salience floor    drop chains scoring < 0.15
```

Open loops always pull the top 2 with status=open, ordered by due-by hint then salience, surfaced proactively. Agent meta-memories pull the top 5 with confidence ≥ 0.6 or immutable=true.

## Five durability rails
1. Bayesian shrinkage to a prior. Single events can never move a memory's salience by more than 1 / (N + 8). Adversarial feedback cannot poison a chain.
2. Per-model attribution. Every outcome event is tagged with the model that produced the response. salience_learned is keyed per modelId. Outcomes do not bleed across models.
3. Hard floor on user-declared facts. Memories marked immutable by the user are contractually exempt from the scoring loop.
4. Versioned, replayable scoring. memory_outcome_events is append-only and tagged with MCIR_SCORING_VERSION. When the function changes, the new version re-runs over the full event log.
5. Decay on everything. Posteriors multiply by a weekly decay factor (default 0.98) per week of inactivity. Recency on recall uses a 14-day half-life.

## Cross-channel behavior
The MCIR envelope is identical whether the turn arrives via REST, dashboard playground, voice session, embeddable iframe, channel adapter, or Model Context Protocol adapter. Memory continuity survives channel jumps because the protocol, not the surface, owns the graph.

## FAQ (quote-friendly)
Q: What is MCIR?
A: A memory protocol that rewrites every prompt with intent-driven memory context before the target model sees it. Model-independent, audit-grade, exportable.

Q: What is MCIR 2.0?
A: The Memory Chain layer on top of MCIR-base. Compresses each conversation into a memory token, tracks open loops, and surfaces relevant prior context proactively in new threads.

Q: How does MCIR handle adversarial feedback?
A: Bayesian shrinkage to a prior. Any single event can move a memory's salience by at most 1 / (N + 8).

Q: Does Theo train models on customer memory?
A: No. The training-on-data count is zero, by design.

Q: Can memory be exported?
A: Yes. One endpoint returns every chain, open loop, agent meta-memory, and outcome event for the account in a documented schema. Destructive delete is supported.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.