Documentation

Chat and workflow agents

Northsun (formerly Mnemix) is the memory and enrichment layer for AI agents: you build and run the agent, and Northsun stores and returns the context it works from. Its hosted MCP server contains an evolving context loop for chat, coding, and workflow agents: request relevant context before work, observe durable learning after work, and report which returned memories helped or conflicted. This surface is beta; use tool discovery and an authenticated lifecycle test as the contract for your tenant.

Stable REST and beta MCP are different contracts

The frozen public REST contract is the three-endpoint caller-memory lifecycle. The broader observe, context, and feedback tools route to evolving memory endpoints and are not part of that frozen REST guarantee.

Use this guide when:

  • your MCP client discovers all three tools;
  • your beta agreement names the identifiers and behavior you depend on; and
  • a controlled tenant proves the full asynchronous lifecycle.

If any condition is missing, use the frozen caller API or wait for the broader contract to graduate.

The lifecycle

current task
  -> context(query, identifier, surface)
  -> agent uses selected context
  -> observe(identifiers, transcript, surface)
  -> asynchronous memory processing

1. Request context before work

Use a stable identifier owned by your application, such as user_id or email. Ask a specific question; a generic request for everything produces a less testable result.

{
  "query": "What constraints and unresolved decisions matter for this task?",
  "identifier": {
    "user_id": "test_user_01"
  },
  "surface": "chat",
  "max_tokens": 800
}

Retain the returned packet_id — also returned on the X-Context-Packet-Id response header — and the memory identifiers. Do not assume every returned item is correct merely because retrieval selected it; apply the authority, evidence, and temporal signals present in the packet.

2. Observe durable learning after work

Submit information worth carrying into another session—not every transient tool output.

{
  "identifiers": {
    "user_id": "test_user_01"
  },
  "transcript": [
    {
      "role": "user",
      "text": "Use the staging tenant for tomorrow's verification."
    },
    {
      "role": "agent",
      "text": "I will keep production unchanged and verify in staging."
    }
  ],
  "surface": "chat",
  "source": "controlled-docs-test",
  "metadata": {
    "session_id": "session_01"
  }
}

observe is asynchronous. Its acknowledgement does not prove that a memory is already retrievable. Poll with a bounded test strategy or wait for the processing receipt named in your beta contract.

3. Retrieval feedback does not chain from the context path

The feedback tool requires a context_audit_id, and the context path does not produce one. The context call returns packet_id and the X-Context-Packet-Id header; packet_id is not a context_audit_id and is rejected. Do not wire context → feedback as consecutive steps.

The identifier is produced by recall_and_enrich, which returns context_audit_id together with the ids of the facts it served, on deployments where the voice feedback loop is enabled. Feedback adjusts only memories you name by id, so a verdict carrying no ids is recorded and moves nothing. If your agent is on the context path rather than the recall path, treat retrieval feedback as unavailable and do not build a lifecycle that depends on closing it.

Prove cross-session behavior

A successful MCP connection proves transport and authentication, not persistent context. Use a controlled test:

  1. Inspect tools/list and retain the enabled tool names.
  2. Request context for a new test entity and record the empty or baseline result.
  3. Submit one unique durable observation.
  4. Wait or poll according to the tenant's asynchronous-processing contract.
  5. Request context for the same entity with a query that should select the observation.
  6. Verify the returned evidence, packet_id, and memory ID.

Only then describe the exact behavior you observed. This test does not prove proactive Beacon delivery, universal client support, or behavior for a different tenant.

Production boundaries

  • Keep API keys in client-supported secret or environment-variable storage.
  • Separate user identifiers by tenant and application policy.
  • Treat tool output and external content as untrusted input, not permission to rewrite durable behavioral rules.
  • Bound retries for asynchronous operations; do not create an observe storm.
  • Log request/audit identifiers and redacted correlation data, never raw keys or unnecessary transcripts.
  • Re-run the lifecycle proof after changing the MCP client, the Northsun tool contract, identifier mapping, or agent prompt.

Next steps