Decision logging — write agent decisions to agent-memory per session

[canoo]

Problem

Architectural decisions made during a session (which library to use, why a pattern was chosen, what was ruled out) live only in the conversation transcript and are lost when the session ends. The next session — or the next tool — has no record of them.

Research shows 'agentic drift' is a growing concern: AI-generated code quality degrades across sessions as context is lost, driving demand for tools that enforce strict decision logging and steering (r/PromptEngineering, April 2026).

Solution

When the nexus-context MCP server (#84) is active, any tool can call nexus_log_decision(what, why) to write a structured entry to agent-memory:

<!-- .nexus/memory/decisions.md -->
## 2026-04-28 — JWT over sessions
Chose JWT for auth because the API needs to be stateless for horizontal scaling.
Ruled out: cookie sessions (stateful), OAuth (too heavy for internal API).

## 2026-04-27 — Postgres over SQLite
SQLite insufficient for concurrent writes from multiple agent workers.

Automatic capture

For decisions that don't warrant an explicit call, the orchestrator persona can be instructed to call nexus_log_decision whenever it:

• Chooses between two architectural options
• Defers a task to a later session
• Overrides a previous pattern

Read-back

nexus_get_context() includes recent decisions in its response, so the next session (even in a different tool) has this context loaded automatically.

Dependencies

Requires #84 (nexus-context MCP server).