Schema · Retrieval

Retrieval, agents and limits

The last block of sections is what an agent actually consumes at runtime: chunks for RAG, atomic units for fine-grained recall, behavior rules for itself, and an honest list of what the package does not know.

retrieval_chunks

interface RetrievalChunk {
  id: string;                    // chk_*
  title: string;
  standalone_context: string;    // self-contained: no external refs needed
  compressed_knowledge: string;  // dense restatement
  activation_queries: string[];  // questions this chunk answers
  related_rules: string[];
  related_entities: string[];
  related_concepts: string[];
}

atomic_units

interface AtomicUnit {
  id: string;                    // atm_*
  statement: string;             // single, indivisible knowledge claim
  type: "fact" | "rule" | "definition" | "claim" | "heuristic";
  tags: string[];
  dependencies: string[];        // ids of other atomic units
  confidence: number;
}

agent_instructions

interface AgentInstructions {
  behavior_rules: string[];
  reasoning_rules: string[];
  response_rules: string[];
  forbidden_behaviors: string[];
  preferred_questions: string[];
  tool_usage_guidance: string[];
}

knowledge_limits

interface KnowledgeLimits {
  missing_context: string[];
  weakly_supported_claims: string[];
  assumptions_detected: string[];
  possible_biases: string[];
  outdated_sections: string[];
  needs_human_review: string[];
}

source_traceability

interface SourceTraceItem {
  extracted_item_id: string;     // id of any item in the package
  source_location: string;       // page, section, timestamp, line range, ...
  source_excerpt: string;        // verbatim quote
  extraction_type: SourceBasis;
}

Combined example

yaml

retrieval_chunks:
  - id: chk_spacing_intervals
    title: "Spacing intervals and decay"
    standalone_context: "Spaced retrieval reactivates memory traces before they decay; intervals must grow but not exceed the trace's lifetime."
    compressed_knowledge: "Grow intervals; cap before failure."
    activation_queries:
      - "How often should I review?"
      - "What happens if I wait too long?"
    related_rules: [pri_grow_intervals, ift_long_gap_drops_accuracy]
    related_entities: [ent_spaced_retrieval]
    related_concepts: [con_consolidation, con_decay]

agent_instructions:
  behavior_rules: ["Cite source_traceability when stating a rule."]
  reasoning_rules: ["Prefer principles over heuristics when both apply."]
  response_rules: ["Mark inferences explicitly when source_basis != explicit."]
  forbidden_behaviors: ["Invent procedures not present in the package."]
  preferred_questions: ["What is the learner's current spacing?"]
  tool_usage_guidance: ["Use the quiz tool only for chunks with type=fact."]