> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec 094 v0 4 memorules delta

# SPEC-094 v0.4 — Memorules Delta (Behavioral Memory Records)

**Status:** draft — Donna engineering proposal; routed to Texi for architecture review.
**Author:** Donna
**Reviewer (architecture):** Texi
**Reviewer (governance):** Candi
**Final operator approver:** Frank
**Origin:** Plan 003 Phase 2 Step 2.1 (signal `94ccc816` Candi-relayed Frank go-signal `8ac87b0d`).

> This is a **delta** spec. v0.3 (the BIOS auto-memory kill-switch + TriGraph substrate) is the base; v0.4 layers a typed-record contract on top so behavioral memory has a *schema*, not just a *namespace*. v0.3 stays unchanged as the substrate-rule.

## Summary

v0.3 said: persona behavioral memory lives in TriGraph; local auto-memory is forbidden. The substrate is sound but **shapeless**: every behavioral fact is a free-text note keyed on persona + project. v0.4 adds a typed-record contract — **Memorules** — so writes are typeable, queryable by kind, and auditable (Watson hooks) without bolting on a separate spec.

Memorules is **vocabulary, not new authority**. Records are advisory by default; their authority comes from the rules+rights model already in SPEC-085 / SPEC-077, not from being typed. Same governance precedence applies.

## Scope of v0.4 delta (what's NEW)

1. **Memorule typed-record schema.** A Memorule is a `prism_remember` write with `kind="memorule"` and one of these `memorule_kind` subtypes:
   * `behavioral_rule` — "always do X; never do Y."
   * `feedback` — operator or peer correction in response to a specific action.
   * `preference` — stylistic/operational preference without a hard rule.
   * `correction` — observed mistake + the right move; can imply a postmortem follow-on.
   * `convention` — a project-wide pattern the persona should respect.

2. **Required fields for Memorules:**
   * `memorule_kind` (one of the above)
   * `subject` (concise rule statement)
   * `body` (full text)
   * `applies_to` (`{persona?: str, surface?: str, specialization?: str, scope?: 'global'|'org'|'project'|'persona'}` — at least one key)
   * `evidence_signal_id` (optional — signal/postmortem/delta that prompted this)
   * `confidence` (`'observed'|'inferred'|'asserted'` — see Confidence section)

3. **Query path.** `semantic_recall(source_type='memorule', ...)` returns Memorules first, ranked by `applies_to` overlap with the active session context. Existing `source_type='memory'` continues to return all memory sources (Memorules included, mixed with general).

4. **Write routing.** `prism_remember(kind='memorule', memorule_kind=..., ...)` is the canonical entry. `prism_remember` without `kind=memorule` continues to write a free-text note as today; v0.4 does not break existing writes.

5. **Watson hooks.** Memorule writes emit a structured audit event in TriGraph: `(memorule_id, written_by_session_id, written_by_persona, evidence_signal_id, written_at)`. Future Watson SPEC reads these audit events to prove "this rule was actually applied at decision time." v0.4 emits the events; consumption is deferred to the Watson SPEC.

## Confidence levels

Three explicit levels (`memorule.confidence`):

* **observed** — the persona directly witnessed the rule in operation (e.g. operator gave correction in chat). Highest weight in retrieval.
* **inferred** — derived by the persona from a pattern across signals/deltas (e.g. "Frank uses Donna for engineering, Texi for architecture"). Medium weight.
* **asserted** — claimed by the persona without explicit observation or pattern (e.g. self-described preferences). Lowest weight.

Retrieval ranking sums confidence-weighted scores; ties broken by `written_at` (newer wins). This is light v0.4 ranking; heavier scoring lives in future Recallgate (Dewey) work.

## Schema (TriGraph)

Memorule is a `:Memory` node subtype with these property additions on `:MemoryState`:

```cypher theme={null}
(:Memory {
  id: <uuid>,
  tenant_id: <uuid>,
  project_id: <uuid>,
  kind: "memorule",                  // existing field, new value
  source_type: "memorule"            // for source_type filter
})-[:HAS_STATE]->(:MemoryState {
  memorule_kind: "behavioral_rule" | "feedback" | "preference" | "correction" | "convention",
  subject: <str>,
  body: <str>,
  applies_to: {persona?, surface?, specialization?, scope?},
  evidence_signal_id: <uuid?>,
  confidence: "observed" | "inferred" | "asserted",
  written_by_session_id: <uuid>,
  written_by_persona: <str>,
  written_at: <iso8601>
})
```

No new node types. Reuses existing `:Memory` / `:MemoryState` topology per SPEC-020.

## Write contract — `prism_remember(kind='memorule', ...)`

Required arguments when `kind=='memorule'`:

* `memorule_kind: str`
* `subject: str` (≥4 chars)
* `body: str` (≥10 chars)
* `applies_to: dict` (must have at least one of persona/surface/specialization/scope)

Optional:

* `evidence_signal_id: str`
* `confidence: str` (defaults to `inferred` if omitted)

Validation errors return structured field-level errors per existing `prism_remember` convention.

## Read contract — `semantic_recall(source_type='memorule', ...)`

Filters by `source_type='memorule'`. Existing args (`query`, `top_k`, `namespace`) all continue to work. Result envelope adds `memorule_kind`, `applies_to`, `confidence`, `evidence_signal_id` to each match.

## What v0.4 does NOT do

* **Does not deprecate free-text notes.** Existing `prism_remember(kind='note', ...)` writes continue. Memorules are an additive type.
* **Does not implement Watson consumption.** v0.4 only emits the audit events. Watson SPEC (separate, future) reads them.
* **Does not add new authority.** Memorules are advisory records; rule authority remains under SPEC-085 / SPEC-077.
* **Does not gate on Recallgate.** Recallgate (SPEC-097 or next-available, draft pending) will read Memorules but doesn't block this delta.
* **Does not migrate any existing free-text notes.** Backfill is out of scope; new writes use the new contract.

## Acceptance criteria

1. Texi architecture sign-off (verdict `approved` or `approved_with_required_revisions`).
2. Candi governance ratification (status flip draft → approved).
3. Backend: `prism_remember(kind='memorule', ...)` validation + write paths in `backend/app/services/memorule_service.py` (new) + integration with existing `memory_service.py`.
4. Backend: `semantic_recall(source_type='memorule', ...)` filter path.
5. Backend: Watson audit event emission on every Memorule write (separate `:MemoruleAudit` node or property block on `:MemoryState`).
6. Tests: `backend/tests/test_memorule_service.py` covering write validation, read filter, audit event shape, missing required fields, all five `memorule_kind` values, all three `confidence` levels.
7. End-to-end smoke: write a Memorule via prism\_remember, recall it via semantic\_recall(source\_type='memorule'), verify Watson audit event shape.

## Phasing

* **Phase 1 (this v0.4):** spec ratify + backend implementation + tests.
* **Phase 2 (separate, deferred):** Recallgate (Dewey) reads Memorules in retrieval gating.
* **Phase 3 (separate, deferred):** Watson SPEC consumes the audit events for proof-of-application surfaces.

## Cross-references

* SPEC-094 v0.3 (substrate; this delta does not modify v0.3 — they coexist)
* SPEC-085 v0.2 — constitutional governance + rule authority (Memorules respect, do not extend)
* SPEC-077 — governance precedence (narrower-wins still applies to Memorules-derived advisories)
* SPEC-020 — TriGraph memory topology (no schema migration required)
* Plan 003 (memory activation Miranda-style) — Phase 2
* method.wall-break.persistence v0.2 — Element 5 (recall-on-task-start) reads Memorules
* (future) Recallgate SPEC — consumer
* (future) Watson SPEC — consumes audit events

## Risk

* **R2** — adds new typed-record contract on existing TriGraph substrate. No breaking change to existing memory paths; new write/read contract is additive.
* Confidence-level ranking in v0.4 is intentionally simple; sophisticated scoring deferred to Recallgate.