Mini-Nav/AGENTS.md

Memorix — Automatic Memory Rules

You have access to Memorix memory tools. Follow these rules to maintain persistent context across sessions.

RULE 1: Session Start — Bind Project, Then Load Context

At the beginning of every conversation, BEFORE responding to the user:

1. Call memorix_session_start with parameters:
   • agent: your agent identifier (e.g. "windsurf", "codex", "antigravity")
   • projectRoot: the absolute path of the current workspace or repo root This binds the session to the correct project. Without projectRoot, memories may go to the wrong bucket.
2. Then call memorix_search with a query related to the user's first message for additional context
3. If search results are found, use memorix_detail to fetch the most relevant ones
4. Reference relevant memories naturally — the user should feel you "remember" them

Important: projectRoot is a detection anchor only; Git remains the source of truth for project identity. In HTTP control-plane mode (memorix serve-http / memorix background start), explicit projectRoot binding is required for correct multi-project isolation. memorix_session_start is lightweight by default: it starts memory/session context only. Do not set joinTeam unless the user explicitly needs autonomous Agent Team tasks, messages, file locks, or orchestrated CLI-agent workflows.

RULE 2: Store Important Context

Proactively call memorix_store when any of the following happen:

What MUST be recorded:

• Architecture/design decisions → type: decision
• Bug identified and fixed → type: problem-solution
• Unexpected behavior or gotcha → type: gotcha
• Config changed (env vars, ports, deps) → type: what-changed
• Feature completed or milestone → type: what-changed
• Trade-off discussed with conclusion → type: trade-off

What should NOT be recorded:

• Simple file reads, greetings, trivial commands (ls, pwd, git status)

Use topicKey for evolving topics:

For decisions, architecture docs, or any topic that evolves over time, ALWAYS use topicKey parameter. This ensures the memory is UPDATED instead of creating duplicates. Use memorix_suggest_topic_key to generate a stable key.

Example: topicKey: "architecture/auth-model" — subsequent stores with the same key update the existing memory.

Track progress with the progress parameter:

When working on features or tasks, include the progress parameter:

{
  "progress": {
    "feature": "user authentication",
    "status": "in-progress",
    "completion": 60
  }
}

Status values: in-progress, completed, blocked

RULE 3: Resolve Completed Memories

When a task is completed, a bug is fixed, or information becomes outdated:

1. Call memorix_resolve with the observation IDs to mark them as resolved
2. Resolved memories are hidden from default search, preventing context pollution

This is critical — without resolving, old bug reports and completed tasks will keep appearing in future searches.

RULE 4: Session End — Store Decision Chain Summary

When the conversation is ending, create a decision chain summary (not just a checklist):

1. Call memorix_store with type session-request and topicKey: "session/latest-summary":

   Required structure:

   ## Goal
   [What we were working on — specific, not vague]
   
   ## Key Decisions & Reasoning
   - Chose X because Y. Rejected Z because [reason].
   - [Every architectural/design decision with WHY]
   
   ## What Changed
   - [File path] — [what changed and why]
   
   ## Current State
   - [What works now, what's pending]
   - [Any blockers or risks]
   
   ## Next Steps
   - [Concrete next actions, in priority order]
   

   Critical: Include the "Key Decisions & Reasoning" section. Without it, the next AI session will lack the context to understand WHY things were done a certain way and may suggest conflicting approaches.

2. Call memorix_resolve on any memories for tasks completed in this session

RULE 5: Compact Awareness

Memorix automatically compacts memories on store:

• With LLM API configured: Smart dedup — extracts facts, compares with existing, merges or skips duplicates
• Without LLM (free mode): Heuristic dedup — uses similarity scores to detect and merge duplicate memories
• You don't need to manually deduplicate. Just store naturally and compact handles the rest.
• If you notice excessive duplicate memories, call memorix_deduplicate for batch cleanup.

Guidelines

• Use concise titles (~5-10 words) and structured facts
• Include file paths in filesModified when relevant
• Include related concepts for better searchability
• Always use topicKey for recurring topics to prevent duplicates
• Always resolve completed tasks and fixed bugs
• Always include reasoning — "chose X because Y" is 10x more valuable than "did X"
• Search defaults to status="active" — use status="all" to include resolved memories

Beyond These Rules

This file contains the minimum operating rules for Memorix memory tools. It is NOT the complete truth about runtime behavior, support tiers, or team semantics.

For authoritative, up-to-date details on:

• Support tiers (core / extended / community) and what "installed" vs "runtime-ready" means
• HTTP control-plane binding and projectRoot isolation rules
• Opt-in team semantics (joinTeam, team_manage join, roles, task claim, handoff validation)
• Install vs runtime-ready distinction — hook config written ≠ agent will execute it
• Agent-specific caveats (Copilot project-level only, OpenCode plugin lifecycle, etc.)

→ Read docs/AGENT_OPERATOR_PLAYBOOK.md in the Memorix source or npm package.

If this file and the playbook conflict, the playbook is authoritative.