cherry-docs 0.2.0__py3-none-any.whl

app/services/internal_memory_agent.py

@@ -0,0 +1,214 @@
+"""Provider-agnostic internal memory-agent: prompt building, LLM extraction, chunked pipeline."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+from app.services.memory_extraction_normalize import (
+    MemoryCandidate,
+    MemoryExtractionResult,
+    _is_near_duplicate,
+    normalize_memory_candidates,
+)
+from app.services.memory_profiles import (
+    MemoryPromptProfile,
+    MemoryPromptProfileName,
+    resolve_memory_prompt_profile,
+)
+from app.services.memory_providers import AnthropicMemoryProvider, OllamaMemoryProvider
+
+_CHUNK_SIZE = 25          # events per LLM call
+_MAX_TOTAL_CANDIDATES = 12  # cap across all chunks for one session
+
+
+class MemoryModelProvider(Protocol):
+    def extract(self, prompt: str) -> dict[str, Any]:
+        """Return parsed JSON-like extraction payload."""
+
+
+def _trim_text(value: str, limit: int = 1200) -> str:
+    text = " ".join((value or "").split())
+    if len(text) <= limit:
+        return text
+    return f"{text[: limit - 3]}..."
+
+
+def build_recent_capture_window(events: Iterable[dict[str, Any]], limit: int = _CHUNK_SIZE) -> list[dict[str, Any]]:
+    relevant: list[dict[str, Any]] = []
+    for event in events:
+        event_type = str(event.get("event_type") or "")
+        if event_type not in {
+            "user_prompt",
+            "assistant_output",
+            "shell_result",
+            "tool_result",
+            "remember",
+            "test_result",
+        }:
+            continue
+        text = str(event.get("text") or "").strip()
+        if not text and event_type not in {"shell_result", "tool_result", "test_result"}:
+            continue
+        relevant.append(event)
+    return relevant[-max(1, limit):]
+
+
+def build_internal_memory_prompt(
+    events: Iterable[dict[str, Any]],
+    *,
+    project_hint: str | None = None,
+    existing_context: list[str] | None = None,
+    profile: MemoryPromptProfileName | str | None = None,
+) -> str:
+    prompt_profile = resolve_memory_prompt_profile(profile)
+    window = build_recent_capture_window(events)
+    event_lines: list[str] = []
+    for event in window:
+        event_type = str(event.get("event_type") or "unknown")
+        text = _trim_text(str(event.get("text") or ""))
+        command = _trim_text(str(event.get("command") or ""), 240)
+        exit_code = event.get("exit_code")
+        _meta = event.get("metadata")
+        metadata: dict = _meta if isinstance(_meta, dict) else {}
+        parts = [f"type={event_type}"]
+        if command:
+            parts.append(f"command={command}")
+        if exit_code is not None:
+            parts.append(f"exit_code={exit_code}")
+        verification_status = str(metadata.get("verification_status") or "").strip()
+        verification_kind = str(metadata.get("verification_kind") or "").strip()
+        if verification_kind:
+            parts.append(f"verification_kind={verification_kind}")
+        if verification_status:
+            parts.append(f"verification_status={verification_status}")
+        if text:
+            parts.append(f"text={text}")
+        event_lines.append(" | ".join(parts))
+
+    prior = "\n".join(f"- {item}" for item in (existing_context or []) if item) or "- none"
+    rendered_events = "\n".join(f"- {line}" for line in event_lines) or "- none"
+    project_label = project_hint or "current project"
+    keep_rules = "\n".join(f"- {line}" for line in prompt_profile.keep_rules)
+    extra_rules = "\n".join(f"- {line}" for line in prompt_profile.extra_rules)
+    extraction_bias = "\n".join(f"- {line}" for line in prompt_profile.extraction_bias)
+    schema = {
+        "candidates": [
+            {
+                "memory_type": "episodic|heuristic|procedural|factual|noise",
+                "kind": "attempt|decision|conclusion|warning|procedure|pattern|fact",
+                "summary": "short useful memory",
+                "rationale": "why this matters for a future AI",
+                "confidence": 0.0,
+                "should_store": True,
+                "sensitive": False,
+            }
+        ],
+        "notes": ["optional short notes"],
+    }
+    return f"""You are CherryDocs' internal memory distiller for {project_label}.
+
+Your job is to turn recent AI work traces into useful shared project memory.
+
+Active profile: {prompt_profile.name}
+Profile intent: {prompt_profile.description}
+
+{prompt_profile.system_focus}
+{keep_rules}
+
+Memory type rules:
+- factual = what is permanently true right now: a command, path, config, API, or project state
+- episodic = a concrete attempt, decision, or conclusion from this work
+- heuristic = a reusable warning, hidden constraint, or recurring pattern
+- procedural = an explicit step-by-step way of doing something repeatedly
+- noise = routine chatter, weak summaries, or anything cheap to rediscover
+
+Kind rules:
+- fact = stable project truth: entry points, config paths, APIs, project-level invariants. NOT test results or error counts.
+- attempt = "we tried X"
+- decision = "we chose X over Y because..."
+- conclusion = "we learned/found that..."
+- warning = "avoid X because..."
+- pattern = "X keeps happening when..."
+- procedure = a repeatable workflow with actual steps
+
+Important:
+- Never store a fact whose value changes daily: test pass counts, lint error totals, CI status, PR review status.
+- Use procedure only for explicit repeatable workflows; prefer decision for refactors/pivots.
+- If a candidate is noise, set memory_type=noise and should_store=false.
+- If no durable memory is present, return an empty candidates list.
+- Return at most 3 non-overlapping candidates.
+{extra_rules}
+
+Prefer extracting:
+{extraction_bias}
+
+Output strict JSON only.
+
+Prior remembered context:
+{prior}
+
+Recent captured events:
+{rendered_events}
+
+Return JSON matching this schema:
+{json.dumps(schema, indent=2)}
+"""
+
+
+def extract_memory_candidates(
+    events: Iterable[dict[str, Any]],
+    *,
+    provider: MemoryModelProvider,
+    project_hint: str | None = None,
+    existing_context: list[str] | None = None,
+    profile: MemoryPromptProfileName | str | None = None,
+) -> MemoryExtractionResult:
+    """Extract memories from all events in chunks, accumulating across the full session."""
+    all_events = list(events)
+    relevant = build_recent_capture_window(all_events, limit=len(all_events) or 1)
+    if not relevant:
+        return MemoryExtractionResult()
+
+    accumulated: list[Any] = []
+    running_context = list(existing_context or [])
+    notes: list[str] = []
+
+    for i in range(0, len(relevant), _CHUNK_SIZE):
+        chunk = relevant[i: i + _CHUNK_SIZE]
+        prompt = build_internal_memory_prompt(
+            chunk,
+            project_hint=project_hint,
+            existing_context=running_context,
+            profile=profile,
+        )
+        result = normalize_memory_candidates(provider.extract(prompt))
+        notes.extend(result.notes)
+        for candidate in result.candidates:
+            if candidate.memory_type == "noise" or not candidate.should_store:
+                continue
+            if not any(_is_near_duplicate(candidate, seen) for seen in accumulated):
+                accumulated.append(candidate)
+                running_context = [*running_context, candidate.summary]
+        if len(accumulated) >= _MAX_TOTAL_CANDIDATES:
+            break
+
+    return MemoryExtractionResult(candidates=accumulated[:_MAX_TOTAL_CANDIDATES], notes=notes)
+
+
+__all__ = [
+    # Re-exported from sub-modules so callers import from here unchanged.
+    "AnthropicMemoryProvider",
+    "MemoryCandidate",
+    "MemoryExtractionResult",
+    "MemoryModelProvider",
+    "MemoryPromptProfile",
+    "MemoryPromptProfileName",
+    "OllamaMemoryProvider",
+    "build_internal_memory_prompt",
+    "build_recent_capture_window",
+    "extract_memory_candidates",
+    "normalize_memory_candidates",
+    "resolve_memory_prompt_profile",
+]

app/services/memory_evidence.py

@@ -0,0 +1,89 @@
+"""Evidence linking: connect memory candidates to their supporting raw capture events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from app.services.memory_similarity import _similarity
+
+if TYPE_CHECKING:
+    from app.services.memory_extraction_normalize import MemoryCandidate
+
+
+def build_event_evidence_id(event: dict) -> str:
+    event_type = str(event.get("event_type") or "unknown")
+    timestamp = str(event.get("timestamp") or "unknown")
+    return f"{event_type}:{timestamp}"
+
+
+def collect_candidate_evidence_refs(
+    candidate: MemoryCandidate,
+    events: list[dict],
+    *,
+    limit: int = 3,
+) -> list[str]:
+    ranked: list[tuple[float, str]] = []
+    summary_anchor = candidate.summary.strip()
+    rationale_anchor = candidate.rationale.strip()
+    combined_anchor = f"{summary_anchor} {rationale_anchor}".strip()
+    for event in events:
+        event_type = str(event.get("event_type") or "")
+        if event_type not in {"assistant_output", "remember", "tool_result", "shell_result", "test_result"}:
+            continue
+        text = str(event.get("text") or "").strip()
+        if not text:
+            continue
+        summary_overlap = _similarity(summary_anchor, text)
+        rationale_overlap = _similarity(rationale_anchor, text) if rationale_anchor else 0.0
+        overlap = _similarity(combined_anchor, text)
+        if summary_overlap < 0.35 and not (summary_overlap >= 0.2 and rationale_overlap >= 0.2):
+            continue
+        score = (summary_overlap * 1.7) + rationale_overlap + (overlap * 0.4)
+        if event_type == "assistant_output":
+            score += 0.2
+        ranked.append((score, build_event_evidence_id(event)))
+    ranked.sort(key=lambda item: item[0], reverse=True)
+    return [evidence_id for _, evidence_id in ranked[: max(1, limit)]]
+
+
+def collect_candidate_context(
+    candidate: MemoryCandidate,
+    events: list[dict],
+    *,
+    evidence_refs: list[str] | None = None,
+    max_files_per_event: int = 20,
+    max_files_total: int = 5,
+) -> dict:
+    matched_ids = set(evidence_refs or collect_candidate_evidence_refs(candidate, events))
+    if not matched_ids:
+        return {"repo": None, "commit": None, "files": []}
+
+    repo: str | None = None
+    commit: str | None = None
+    weighted_files: dict[str, int] = {}
+    for event in events:
+        event_id = build_event_evidence_id(event)
+        if event_id not in matched_ids:
+            continue
+        if not repo:
+            repo = str(event.get("repo") or "").strip() or None
+        if not commit:
+            commit = str(event.get("commit") or "").strip() or None
+        _raw_files = event.get("files")
+        event_files = [
+            str(p).strip()
+            for p in (_raw_files if isinstance(_raw_files, list) else [])
+            if str(p).strip()
+        ]
+        if not event_files or len(event_files) > max_files_per_event:
+            continue
+        for path in event_files:
+            weighted_files[path] = weighted_files.get(path, 0) + 1
+
+    files = [
+        path
+        for path, _count in sorted(
+            weighted_files.items(), key=lambda item: (-item[1], item[0])
+        )[:max_files_total]
+    ]
+    return {"repo": repo, "commit": commit, "files": files}

app/services/memory_extraction_normalize.py

@@ -0,0 +1,134 @@
+"""Output normalization and deduplication for LLM-extracted memory candidates."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_VALID_MEMORY_TYPES = {"episodic", "heuristic", "procedural", "factual", "noise"}
+_VALID_KINDS = {"attempt", "decision", "conclusion", "warning", "procedure", "pattern", "fact"}
+_KINDS_BY_MEMORY_TYPE = {
+    "episodic": {"attempt", "decision", "conclusion"},
+    "heuristic": {"warning", "pattern"},
+    "procedural": {"procedure"},
+    "factual": {"fact"},
+    "noise": _VALID_KINDS,
+}
+_MEMORY_TYPE_BY_KIND = {
+    "attempt": "episodic",
+    "decision": "episodic",
+    "conclusion": "episodic",
+    "warning": "heuristic",
+    "pattern": "heuristic",
+    "procedure": "procedural",
+    "fact": "factual",
+}
+_STOPWORDS = {
+    "a", "an", "and", "are", "as", "at", "be", "because", "for", "from", "how",
+    "if", "in", "into", "is", "it", "of", "on", "or", "over", "that", "the",
+    "this", "to", "use", "we", "with",
+}
+_PROCEDURE_HINTS = {"step", "steps", "first", "then", "next", "run", "repeat", "workflow", "checklist"}
+_DECISION_HINTS = {"choose", "decide", "switch", "move", "refactor", "introduce", "keep", "adopt", "use"}
+_TRANSIENT_RE = re.compile(
+    r"ruff |pytest |tests? (pass|fail)|\d+ (error|test)|pr (is |was )?(clean|ready)|dead code removed",
+    re.IGNORECASE,
+)
+
+
+class MemoryCandidate(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    memory_type: str
+    kind: str
+    summary: str
+    rationale: str = ""
+    confidence: float = 0.0
+    should_store: bool = True
+    sensitive: bool = False
+
+
+class MemoryExtractionResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    candidates: list[MemoryCandidate] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+def _canonical_tokens(value: str) -> set[str]:
+    return {
+        token
+        for token in re.findall(r"[a-z0-9]+", value.lower())
+        if token and token not in _STOPWORDS and len(token) > 2
+    }
+
+
+def _is_near_duplicate(left: MemoryCandidate, right: MemoryCandidate) -> bool:
+    left_tokens = _canonical_tokens(f"{left.summary} {left.rationale}")
+    right_tokens = _canonical_tokens(f"{right.summary} {right.rationale}")
+    if not left_tokens or not right_tokens:
+        return left.summary.strip().lower() == right.summary.strip().lower()
+    overlap = len(left_tokens & right_tokens)
+    smaller = min(len(left_tokens), len(right_tokens))
+    return smaller > 0 and (overlap / smaller) >= 0.7
+
+
+def normalize_memory_candidates(payload: dict[str, Any]) -> MemoryExtractionResult:
+    try:
+        parsed = MemoryExtractionResult.model_validate(payload)
+    except Exception:
+        return MemoryExtractionResult()
+
+    normalized: list[MemoryCandidate] = []
+    for item in parsed.candidates:
+        memory_type = (item.memory_type or "").strip().lower()
+        kind = (item.kind or "").strip().lower()
+        if kind not in _VALID_KINDS:
+            continue
+        if memory_type not in _VALID_MEMORY_TYPES:
+            memory_type = _MEMORY_TYPE_BY_KIND.get(kind, "")
+        if not memory_type:
+            continue
+        if kind not in _KINDS_BY_MEMORY_TYPE.get(memory_type, set()):
+            inferred_type = _MEMORY_TYPE_BY_KIND.get(kind)
+            if inferred_type:
+                memory_type = inferred_type
+        summary = " ".join(item.summary.split()).strip()
+        if not summary or _TRANSIENT_RE.search(summary):
+            continue
+        rationale = " ".join(item.rationale.split()).strip()
+        should_store = bool(item.should_store)
+        if memory_type == "procedural" and kind == "procedure":
+            tokens = _canonical_tokens(f"{summary} {rationale}")
+            if not (tokens & _PROCEDURE_HINTS) and tokens & _DECISION_HINTS:
+                memory_type = "episodic"
+                kind = "decision"
+        if memory_type == "noise":
+            should_store = False
+        candidate = item.model_copy(
+            update={
+                "memory_type": memory_type,
+                "kind": kind,
+                "summary": summary,
+                "rationale": rationale,
+                "confidence": max(0.0, min(1.0, float(item.confidence or 0.0))),
+                "should_store": should_store,
+            }
+        )
+        normalized.append(candidate)
+    normalized.sort(
+        key=lambda c: (not c.should_store, c.memory_type == "noise", -c.confidence, len(c.summary)),
+    )
+    deduped: list[MemoryCandidate] = []
+    for candidate in normalized:
+        if any(_is_near_duplicate(candidate, existing) for existing in deduped):
+            continue
+        deduped.append(candidate)
+        if len(deduped) >= 3:
+            break
+    return MemoryExtractionResult(
+        candidates=deduped,
+        notes=[note for note in parsed.notes if str(note).strip()],
+    )

app/services/memory_lifecycle.py

@@ -0,0 +1,258 @@
+"""Deterministic memory lifecycle helpers for capture-first CherryDocs."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.services.memory_evidence import (
+    build_event_evidence_id,
+    collect_candidate_context,
+    collect_candidate_evidence_refs,
+)
+from app.services.memory_extraction_normalize import MemoryCandidate
+from app.services.memory_similarity import (
+    _best_matching_record,
+    _is_conflict,
+    _is_repeatable_procedure,
+    _should_merge,
+    _should_supersede,
+    topic_key_for_text,
+)
+from app.services.privacy import detect_blocking_secret_fields, redact_text
+
+MemoryStatus = Literal["active", "tentative", "superseded", "stale", "contradicted", "archived"]
+MemoryAction = Literal["create", "merge", "supersede", "conflict", "ignore"]
+
+
+class MemoryRecord(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    memory_id: str
+    memory_type: str
+    kind: str
+    summary: str
+    rationale: str = ""
+    confidence: float = 0.0
+    status: MemoryStatus = "active"
+    topic_key: str = ""
+    project_id: str | None = None
+    source: str | None = None
+    session_id: str | None = None
+    repo: str | None = None
+    branch: str | None = None
+    commit: str | None = None
+    files: list[str] = Field(default_factory=list)
+    evidence: list[str] = Field(default_factory=list)
+    derived_from_paths: list[str] = Field(default_factory=list)
+    supersedes: list[str] = Field(default_factory=list)
+    superseded_by: str | None = None
+    retrieval_count: int = 0
+    evidence_hit_count: int = 0
+    last_retrieved_at: str | None = None
+    last_evidence_hit_at: str | None = None
+    created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+    updated_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+
+class MemoryLifecycleDecision(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    action: MemoryAction
+    reason: str
+    candidate: MemoryCandidate
+    target_memory_id: str | None = None
+    resulting_record: MemoryRecord | None = None
+
+
+class MemoryPromotionResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    decisions: list[MemoryLifecycleDecision] = Field(default_factory=list)
+    records: list[MemoryRecord] = Field(default_factory=list)
+
+
+def build_existing_memory_context(records: list[MemoryRecord], limit: int = 8) -> list[str]:
+    selected = sorted(
+        [record for record in records if record.status in {"active", "tentative"}],
+        key=lambda item: (item.status != "active", -item.confidence, item.updated_at),
+    )[: max(1, limit)]
+    lines: list[str] = []
+    for record in selected:
+        detail = f"{record.memory_type}/{record.kind}: {record.summary}"
+        if record.rationale:
+            detail += f" | why={record.rationale}"
+        if record.status != "active":
+            detail += f" | status={record.status}"
+        lines.append(detail)
+    return lines
+
+
+def sanitize_candidate(candidate: MemoryCandidate) -> MemoryCandidate:
+    payload = {"summary": candidate.summary, "rationale": candidate.rationale}
+    findings = detect_blocking_secret_fields(payload)
+    if findings:
+        return candidate.model_copy(update={"sensitive": True, "should_store": False})
+    return candidate.model_copy(update={
+        "summary": redact_text(candidate.summary),
+        "rationale": redact_text(candidate.rationale),
+    })
+
+
+def age_memory_records(
+    records: list[MemoryRecord],
+    *,
+    now: datetime | None = None,
+    stale_after_days: int = 180,
+) -> list[MemoryRecord]:
+    reference = now or datetime.now(UTC)
+    aged: list[MemoryRecord] = []
+    for record in records:
+        if record.status not in {"active", "tentative"}:
+            aged.append(record)
+            continue
+        try:
+            updated_at = datetime.fromisoformat(record.updated_at)
+        except Exception:
+            aged.append(record)
+            continue
+        age_days = (reference - updated_at).days
+        aged.append(record.model_copy(update={"status": "stale"}) if age_days >= stale_after_days else record)
+    return aged
+
+
+def _make_record(
+    candidate: MemoryCandidate,
+    *,
+    project_id: str | None,
+    source: str | None,
+    session_id: str | None,
+    repo: str | None,
+    branch: str | None,
+    commit: str | None,
+    files: list[str] | None,
+    evidence: list[str] | None,
+    derived_from_paths: list[str] | None = None,
+    supersedes: list[str] | None = None,
+) -> MemoryRecord:
+    return MemoryRecord(
+        memory_id=f"mem-{uuid4().hex[:12]}",
+        memory_type=candidate.memory_type,
+        kind=candidate.kind,
+        summary=candidate.summary,
+        rationale=candidate.rationale,
+        confidence=candidate.confidence,
+        status="tentative" if candidate.confidence < 0.65 else "active",
+        topic_key=topic_key_for_text(candidate.summary, candidate.rationale),
+        project_id=project_id,
+        source=source,
+        session_id=session_id,
+        repo=repo,
+        branch=branch,
+        commit=commit,
+        files=list(files or []),
+        evidence=list(evidence or []),
+        derived_from_paths=list(derived_from_paths or []),
+        supersedes=list(supersedes or []),
+    )
+
+
+def _decide_for_candidate(
+    candidate: MemoryCandidate,
+    records: list[MemoryRecord],
+    *,
+    make_kwargs: dict,
+) -> tuple[MemoryLifecycleDecision, list[MemoryRecord]]:
+    """Return (decision, updated_records) for one candidate."""
+    best = _best_matching_record(candidate, records)
+
+    if best and _should_supersede(candidate, best):
+        replacement = _make_record(candidate, supersedes=[best.memory_id], **make_kwargs)
+        old = best.model_copy(update={"status": "superseded", "superseded_by": replacement.memory_id})
+        updated = [old if r.memory_id == best.memory_id else r for r in records] + [replacement]
+        return MemoryLifecycleDecision(
+            action="supersede", reason=f"supersedes {best.memory_id}",
+            candidate=candidate, target_memory_id=best.memory_id, resulting_record=replacement,
+        ), updated
+
+    if best and _should_merge(candidate, best):
+        merged = best.model_copy(update={
+            "confidence": max(best.confidence, candidate.confidence),
+            "updated_at": datetime.now(UTC).isoformat(),
+            "rationale": candidate.rationale or best.rationale,
+            "repo": make_kwargs.get("repo") or best.repo,
+            "commit": make_kwargs.get("commit") or best.commit,
+            "files": list(dict.fromkeys([*best.files, *(make_kwargs.get("files") or [])])),
+            "evidence": list(dict.fromkeys([*best.evidence, *(make_kwargs.get("evidence") or [])])),
+        })
+        updated = [merged if r.memory_id == best.memory_id else r for r in records]
+        return MemoryLifecycleDecision(
+            action="merge", reason=f"merged into {best.memory_id}",
+            candidate=candidate, target_memory_id=best.memory_id, resulting_record=merged,
+        ), updated
+
+    if best and _is_conflict(candidate, best):
+        record = _make_record(candidate, **make_kwargs)
+        record.status = "contradicted"
+        return MemoryLifecycleDecision(
+            action="conflict", reason=f"conflicts with {best.memory_id}",
+            candidate=candidate, target_memory_id=best.memory_id, resulting_record=record,
+        ), [*records, record]
+
+    created = _make_record(candidate, **make_kwargs)
+    return MemoryLifecycleDecision(
+        action="create", reason="new durable memory candidate",
+        candidate=candidate, resulting_record=created,
+    ), [*records, created]
+
+
+def promote_memory_candidates(
+    candidates: list[MemoryCandidate],
+    *,
+    existing_records: list[MemoryRecord] | None = None,
+    project_id: str | None = None,
+    source: str | None = None,
+    session_id: str | None = None,
+    repo: str | None = None,
+    branch: str | None = None,
+    commit: str | None = None,
+    files: list[str] | None = None,
+    evidence: list[str] | None = None,
+) -> MemoryPromotionResult:
+    records = [r.model_copy(deep=True) for r in (existing_records or [])]
+    decisions: list[MemoryLifecycleDecision] = []
+    make_kwargs = dict(
+        project_id=project_id, source=source, session_id=session_id,
+        repo=repo, branch=branch, commit=commit, files=files, evidence=evidence,
+    )
+    for candidate in candidates:
+        candidate = sanitize_candidate(candidate)
+        if candidate.sensitive or not candidate.should_store or candidate.memory_type == "noise":
+            decisions.append(MemoryLifecycleDecision(
+                action="ignore", reason="noise or sensitive", candidate=candidate,
+            ))
+            continue
+        if (candidate.memory_type == "procedural" and candidate.kind == "procedure"
+                and not _is_repeatable_procedure(candidate.summary, candidate.rationale)):
+            candidate = candidate.model_copy(update={"memory_type": "episodic", "kind": "decision"})
+        decision, records = _decide_for_candidate(candidate, records, make_kwargs=make_kwargs)
+        decisions.append(decision)
+    return MemoryPromotionResult(decisions=decisions, records=age_memory_records(records))
+
+
+# Re-export evidence helpers so callers can import them from here unchanged.
+__all__ = [
+    "MemoryLifecycleDecision",
+    "MemoryPromotionResult",
+    "MemoryRecord",
+    "age_memory_records",
+    "build_event_evidence_id",
+    "build_existing_memory_context",
+    "collect_candidate_context",
+    "collect_candidate_evidence_refs",
+    "promote_memory_candidates",
+    "sanitize_candidate",
+]