The model underneath the commands.
Mneia has a small vocabulary and it is used precisely. Knowing these six ideas is enough to predict what any command will do.
Three operations
Everything Mneia does serves one of three operations. If a feature does not, it does not belong in the product.
| Operation | When it runs | What it produces |
|---|---|---|
| Checkpoint | At a task or day boundary | Typed items written to project memory, with the load-bearing ones held for human confirmation |
| Rehydrate | At the start of a task, and whenever the task changes | The minimal high-signal context slice for that task, under a token budget |
| Handoff | When work changes hands | A receivable artifact: what is done, current state, open questions, constraints, next action |
Checkpoint and rehydrate are available now. Handoff ships in the next milestone; the artifact it produces is described on the handoff page.
The context item
A context item is the unit of project memory. It has a kind, and the kind decides how it is treated during rehydration — a constraint is not scored against a fact and cannot be crowded out by one.
| Kind | What it holds |
|---|---|
decision | Something settled, with the reasoning and the alternative it beat |
constraint | Something that must hold. The kind that must never be dropped from a slice |
open_question | Something unresolved, with an owner and an age |
fact | Something true about the project that is neither a ruling nor a rule |
artifact_ref | A pointer to the real work — a PR, an ADR, a ticket |
note | Context that does not fit the others and is not load-bearing |
Every item carries a load-bearing flag. Load-bearing means the work goes wrong without it, and it is the flag that drives both the confirmation requirement and the rehydration guarantee.
Provenance, and why it is on every line
Every item records who asserted it — a human or an agent, which one, when, and on what basis. That distinction is rendered everywhere the item appears, because it is the distinction that decides what to trust.
A human-confirmed constraint and an unconfirmed agent assertion are not the same object and must not look the same. Most memory products flatten them into one list of facts, which is how a guess acquires the authority of a ruling.
- Human-confirmed — a person read it and said yes. It carries authority.
- Agent-asserted — extracted from a session and not yet confirmed. Useful, and visibly provisional.
- Disputed — an assertion that contradicts a human-confirmed item. Stored, flagged, and never silently applied.
Superseding, not deleting
When something is replaced, the replacement points at what it replaced with supersedesId. The old item stays, marked superseded, with its reasoning intact.
This is the single highest-value behaviour in the product. What was tried and rejected is exactly what a fresh agent will otherwise propose again on Tuesday, and a deleted item cannot warn anyone. Rehydration includes recent supersessions for that reason.
A replacement of a human-confirmed item is never written automatically. It comes back pending, for a human to confirm. An agent may not overrule a person by writing a row.
How a slice is chosen
Rehydration is selection, not compaction and not search. Compaction shrinks the window without knowing the task; semantic search returns what is similar rather than what is load-bearing. Neither is what you want when the thing that must not be dropped is a constraint nobody mentioned in the query.
- The slice is assembled for a stated task, under a token budget you control.
- Per-kind quotas apply, so a pile of similar facts cannot crowd out every constraint.
- Load-bearing active constraints are always included, whatever the budget pressure. This is a rule, not a heuristic, and it is enforced by a test.
- Recent supersessions are included so the agent does not re-propose what was ruled out.
When two sources disagree
| Disagreement | What Mneia does |
|---|---|
| Agent contradicts a human-confirmed item | The human wins, always. The agent assertion is stored as disputed rather than applied. |
| Agent contradicts an agent assertion | Both are kept and flagged. Neither has authority the other lacks. |
| Human contradicts a human | Never auto-resolved. It is surfaced for the two people to settle. |
The last row is the one that matters and the one nobody else implements. Arbitrating between two colleagues is not a decision software should make on their behalf, and quietly picking the newer row is how a team discovers weeks later that a ruling was overwritten.
Workspaces, projects, and who can see what
A workspace is the tenant. A project is a body of work inside it, usually one repository. A session is one run of an agent against a project, and it is what a checkpoint summarises.
Every row carries the workspace it belongs to, and the database enforces isolation with Postgres row-level security rather than relying on the application to remember. Privacy is enforced by controls — scope, retention, residency — not by keeping data on your laptop, because a hosted service cannot honestly promise the latter.