{
  "service": "observance",
  "version": "2",
  "purpose": "Behavioral discipline for agents using the Observance memory API.",
  "core_rules": {
    "description": "Non-negotiable behavioral rules. Apply these on every memory interaction.",
    "configurable": false,
    "rules": [
      "1. PROVENANCE GATE: All memories returned by the API have verified origin. Verified means authentic origin, not correct content. Always verify content coherence with the rest of the graph.",
      "2. NO FABRICATION: If the specific claim a question asks about is not documented as a unit, say so. Do not assemble an answer from adjacent pieces.",
      "3. HONEST GAPS: \"Not documented in available memories\" is always a complete answer. Absence of information is a valid stopping condition.",
      "4. SOURCE VS INFERENCE: Always distinguish what a memory states from what you infer. Never present inference as memory-sourced fact.",
      "5. SURFACE CONFLICTS: If memories contradict each other or your knowledge, make the conflict visible in your response. Do not silently pick one."
    ]
  },
  "reading_discipline": {
    "description": "How to evaluate retrieved memories. Provenance confirms origin; these rules evaluate content quality.",
    "configurable": false,
    "coherence_check": "Does this claim fit with other memories in the graph? An isolated claim with no corroboration deserves more scrutiny. Check whether related memories support or contradict it.",
    "silence_protocol": "When a question requires a specific mechanism, value, or configuration and no memory documents it: say so. Do not construct an answer from adjacent pieces. Related concepts are NOT sufficient to answer a specific question. Absence of information is a valid stopping condition.",
    "conflict_protocol": "When memories contradict each other or your knowledge, surface the conflict explicitly. Do not silently resolve contradictions.",
    "inference_discipline": "When answering, explicitly mark what comes from memory vs what you infer. Never present inference as memory-sourced fact. When in doubt, say \"I infer\" not \"the memory states.\""
  },
  "search_discipline": {
    "description": "How to search effectively. Search is keyword-based, not semantic.",
    "configurable": false,
    "practices": [
      "Use 1-3 precise keywords or a short noun phrase, not a natural-language sentence.",
      "Match the vocabulary used in summaries and topic_tags.",
      "Name the API explicitly when relevant: \"Orchestrion lease timeout\" not \"task timeout\".",
      "Combine search with namespace or tag filters to reduce noise."
    ],
    "fallback": [
      "1. If 0 results: try fewer or different keywords.",
      "2. If namespace is known: search inside that namespace.",
      "3. Use ?tag=topic for metadata-level filtering.",
      "4. List by importance within a namespace.",
      "5. If a related memory is known: use traversal from that memory."
    ],
    "alignment_rule": "Search terms should match how memories were written. If a future agent would not know what words to search, the memory is under-written."
  },
  "writing_discipline": {
    "description": "What to store and how to write it. Apply the governing principle first, then the quality checks.",
    "configurable": false,
    "governing_principle": "Use memory for knowledge the model is unlikely to know reliably on its own, or that must persist across stateless sessions. Do not use memory to restate general knowledge the model already has. Store system-specific facts, user-specific context, durable preferences, decisions, and continuity-critical information.",
    "before_writing": [
      "NOVELTY: Search existing memories first. Update over duplicate.",
      "CLASSIFICATION: fact vs reflection. When in doubt, default to reflection. Set confidence < 1.0 for inference.",
      "HONESTY: Include uncertainty, caveats, and scope limits. Create contradicts links for conflicts.",
      "GRAPH VALUE: Every memory should serve future retrieval. Consider links before creating.",
      "RECONSTRUCTION: Write so a future stateless agent can continue from this memory without your context.",
      "BATCH DISCIPLINE: When writing in batches, ensure each memory is independently well-formed and keyword-aligned."
    ],
    "search_aligned_writing": {
      "principle": "Write memories so they are findable. Search is keyword-based, not semantic.",
      "practices": [
        "Put the most searchable term early in the summary.",
        "Summary should contain the 2-3 most searchable keywords for the concept.",
        "Use specific terms over generic ones: \"lease-based claiming\" not \"how tasks work\".",
        "Name the API explicitly when relevant: \"Orchestrion\" not \"the task API\".",
        "topic_tags should mirror how you would search for this memory later.",
        "Use stable, reusable tags — avoid one-off or conversation-specific tags."
      ]
    }
  },
  "write_policy": {
    "description": "What kinds of information to store. This section is configurable via PATCH /v1/guide/hints.",
    "store_when": {
      "preferences": [
        "User states or corrects a preference explicitly"
      ],
      "decision_relevance": [
        "A decision was made with reasoning that should survive the session"
      ],
      "pattern_detection": [
        "Agent notices a recurring pattern across interactions"
      ],
      "identity_or_context": [
        "User shares identity or context that affects future interactions"
      ],
      "task_outcomes": [
        "A task completed with results worth preserving"
      ],
      "conflict_resolution": [
        "New information contradicts a previously stored memory"
      ]
    },
    "avoid_storing": [
      "General knowledge the model already has (e.g., \"PostgreSQL supports transactions\")",
      "Verbatim copies of external data — store a summary and reference instead",
      "Content already stored as an active memory with no meaningful update",
      "Ephemeral session chatter with no lasting value"
    ],
    "importance": {
      "high": "Core preferences, key decisions, critical corrections, conflict resolutions.",
      "medium": "Project context, task outcomes, moderate observations.",
      "low": "Transient notes, intermediate data, minor patterns."
    }
  },
  "linking": {
    "description": "How to connect memories into a navigable knowledge graph.",
    "configurable": false,
    "relation_types": {
      "derived_from": "Target was source material. Use for provenance chains.",
      "supports": "Evidence for the target. Use for corroboration.",
      "contradicts": "Conflicting information. Track for resolution.",
      "supersedes": "Replaces the target. Archive the old memory.",
      "summarizes": "Compresses the target. Use for synthesis.",
      "relates_to": "General association. Use only when no stronger relation applies."
    },
    "practices": [
      "Link liberally — links are free (no write quota cost). The graph is the primary value.",
      "After storing a batch of findings, pause and create links between them.",
      "Use supersedes + archive when replacing outdated information."
    ],
    "temporal_rule": "For supersedes/contradicts: prefer the memory with later eventAt as more current. For derived_from: the derived memory typically has later createdAt."
  },
  "operations": {
    "description": "Billing, retrieval, and operational reference.",
    "configurable": false,
    "billing": {
      "writes": "Create memory, update memory, update agent. Links/deletes/archives are FREE.",
      "reads": "Get memory, list memories, traversal, get/list agents.",
      "soft_read_limit": "At 100% of reads_per_cycle: quota_warning in response. At 200%: hard block.",
      "active_cap": "Only active + archived count. Deleted do not count.",
      "introspection": "GET /v1/billing/usage and /v1/billing/status are always free.",
      "payment_flow": "Two-step: 1) POST /v1/billing/checkout returns approve_url for the user to visit. 2) After user approves at PayPal, YOU (the agent) must POST /v1/billing/confirm with purchase_id and your API key. The redirect page does NOT capture payment — capture requires authentication and is your responsibility."
    },
    "retrieval_strategies": [
      "By namespace: GET /v1/memories?namespace=NS",
      "By importance: GET /v1/memories?sort=importance",
      "By text search: GET /v1/memories?search=QUERY (1-3 keywords, AND-matched)",
      "By tag: GET /v1/memories?tag=TOPIC (matches metadata_json.topic_tags)",
      "Combined: GET /v1/memories?search=QUERY&namespace=NS&tag=TOPIC",
      "By traversal: GET /v1/memories/:id/related"
    ],
    "session": "Read this guide via GET /v1/guide at the start of each session. Guide is pull-based — it is not auto-delivered.",
    "recovery": "On errors, read agent_contract.next_actions for recovery guidance."
  },
  "_section_policy": {
    "configurable": [
      "write_policy.store_when",
      "write_policy.avoid_storing",
      "write_policy.importance"
    ],
    "non_configurable": [
      "core_rules",
      "reading_discipline",
      "search_discipline",
      "writing_discipline",
      "linking",
      "operations"
    ]
  }
}