Best practices
What separates a memory that works from one that quietly degrades.
Ingestion
Send documents, not fragments. A whole page with its heading and context retrieves far better than the same text split into sentences before it arrives. Chordian chunks for you; pre-chunking discards the context it would have used.
Pin content you are certain about. Auto-routing is good, not infallible. If
you know a document belongs to Finance, say so — mode: "manual" with a
vault_id costs nothing and removes a class of misfiling.
Watch needs_review. Content that fell below the routing threshold lands in
v_unassigned. Left unattended, that becomes a drawer nobody opens, and the
material in it is effectively invisible to department-scoped queries.
Send useful metadata. Source system, author, document date. It costs nothing at write time and gives you filtering you will want later.
Retrieval
Ask questions, not keywords. "What is blocking the Acme deal?" beats "Acme blocker" — the query classifier routes on question shape, and a keyword string tells it very little.
Scope when you can. A department or space filter narrows the candidate set and improves both latency and precision. Scope only when you know the answer is in there; an over-narrow filter produces a confident "no information found".
Use the citations. They are the difference between an answer you can act on and one you have to verify. Surface them in your UI. If a claim carries no marker, it is not grounded.
Stream anything user-facing. Sources arrive before the first token, so a reader sees the grounding immediately rather than watching a spinner.
Quality
Work the contradiction queue. It is a data-quality signal, not a chore. A spike of conflicts from one connector usually means an upstream mapping is wrong — fix the source rather than the symptom.
Reach for both_valid. People changed jobs; deals legitimately moved stage.
Recording a transition preserves history that accept_incoming destroys.
Read the health score by dimension. The grade alone tells you little. Low coverage means thin evidence; low connectivity means isolated entities; low freshness usually means a stalled connector. Three different fixes.
Correct rather than delete. The learning endpoint retires the wrong answer and stores the right one, so the correction is retrievable. Deleting removes the error and teaches nothing.
Security
Use per-memory keys for anything distributed. Agents, edge deployments and
third-party integrations should carry mk_ credentials that reach one memory —
not a tenant-wide key.
Rotate on a schedule, not on an incident. Rotation mints the replacement before revoking the original, so there is an overlap window. Practise it while nothing is on fire.
Verify webhook signatures against the raw body, in constant time. Both halves matter.
Confirm the perimeter is enabled in each environment before relying on it or describing it to anyone else.
Operating
Set the routing threshold expectation with your team. The classifier declines to guess below 0.70. That is a feature, and someone needs to own the review queue.
Alert on budget, not just on errors. Notifications fire at 80% and 100% of the period grant.
Distinguish the two 402s in code. upgrade_required and
insufficient_credits need different handling — one is a sales conversation, the
other is a top-up.