AGENT_SETUP.rbmem

rbmem# RBMEM v1.3 - Rust-Brain Memory Format

meta:
  version: 1.3
  purpose: "RBForge-agent-setup"
  generated_at: "2026-04-29T00:00:00Z"
  last_updated: "2026-04-29T00:00:00Z"
  valid_until: null
  created_by: "RBForge"
  default_expiry_days: null
  compact_mode: minified

[SECTION: rbforge.agent_setup.overview]
type: hermes:memory
graph:
  node_type: "agent_setup"
  relations:
    - to: "rbforge.agent_setup.rust_brain"
      type: "requires"
    - to: "rbforge.agent_setup.install"
      type: "contains"
    - to: "rbforge.agent_setup.runtime_policy"
      type: "contains"
    - to: "rbforge.agent_setup.forge_protocol"
      type: "contains"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  RBForge is a Rust-Brain/RBMEM-based runtime tool creation system.
  Use this RBMEM file as the agent-facing setup brief.

  Core rule:
  - RBForge tools must be persisted through Rust-Brain RBMEM.
  - Use the Rust-Brain rbmem CLI for validation, reads, writes, and inspection.
  - Do not treat this as a plain Markdown-only setup process.

  Repositories:
  - RBForge: https://github.com/DJLougen/RBForge
  - Rust-Brain: https://github.com/DJLougen/Rust-Brain
[END SECTION]

[SECTION: rbforge.agent_setup.rust_brain]
type: hermes:memory
graph:
  node_type: "dependency"
  relations:
    - to: "rbforge.agent_setup.install"
      type: "enables"
    - to: "rbforge.agent_setup.health_check"
      type: "validates"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  Rust-Brain is the required durable memory backend for RBForge.

  Setup requirement:
  - Install or build rbmem from https://github.com/DJLougen/Rust-Brain.
  - Put rbmem on PATH, or set RBMEM_CLI to the rbmem executable path.
  - Use RBMEM files, not ad hoc JSON or Markdown, for durable agent setup.

  Useful Rust-Brain commands:
  - rbmem --help
  - rbmem validate memory.rbmem
  - rbmem read memory.rbmem tools.registry
  - rbmem read memory.rbmem tools.custom.<tool_name>

  If rbmem is unavailable, do not claim RBForge persistence is active.
[END SECTION]

[SECTION: rbforge.agent_setup.install]
type: hermes:memory
graph:
  node_type: "procedure"
  relations:
    - to: "rbforge.agent_setup.rust_brain"
      type: "requires"
    - to: "rbforge.agent_setup.health_check"
      type: "verified_by"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  Install RBForge from the repository root:

  python -m pip install -e .[dev]

  Configure Rust-Brain rbmem:

  export RBMEM_CLI=/path/to/rbmem

  When running from source:

  export PYTHONPATH=src

  Optional Hermes bridge:

  python scripts/install_hermes_bridge.py

  The bridge reads HERMES_HOME, HERMES_RBMEM, and RBMEM_CLI when set.
  Keep setup path-neutral. Do not write user-specific paths into public docs.
[END SECTION]

[SECTION: rbforge.agent_setup.runtime_policy]
type: hermes:memory
graph:
  node_type: "policy"
  relations:
    - to: "rbforge.agent_setup.forge_protocol"
      type: "constrains"
    - to: "rbforge.agent_setup.review_policy"
      type: "contains"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  Forge a tool only when all conditions are true:
  - The missing capability is reusable.
  - The implementation can be small and deterministic.
  - Inputs can be described by a strict JSON object schema.
  - Output can be a JSON-serializable dictionary.
  - The tool does not need secrets or credentials.
  - The tool does not require unsafe filesystem, shell, memory, or network access.

  Do not forge tools for one-off work.
  Do not forge tools that handle credentials, secrets, or tokens.
  Do not bypass Rust-Brain RBMEM persistence.
[END SECTION]

[SECTION: rbforge.agent_setup.forge_protocol]
type: json
graph:
  node_type: "protocol"
  relations:
    - to: "rbforge.agent_setup.runtime_policy"
      type: "governed_by"
    - to: "rbforge.agent_setup.review_policy"
      type: "uses"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  {
    "tool_creation_sequence": [
      "Search tools.registry for an existing suitable tool.",
      "If none exists, decide whether the missing capability is reusable.",
      "If reusable and safe, call forge_tool with a complete Python run(...) implementation.",
      "Provide a strict JSON object schema, category, expected output keys, and sample args when needed.",
      "If forge_tool returns status=registered, call run_forged_tool with task arguments.",
      "If forge_tool returns review_queued, report that review is needed.",
      "If validation fails, fix the proposal once or abandon the forge.",
      "Prefer the registered tool on later tasks."
    ],
    "forge_status_handling": {
      "registered": "Tool is active; run it with run_forged_tool.",
      "review_queued": "Do not run automatically; request review.",
      "sandbox_failed": "Inspect sandbox output and fix implementation.",
      "validation_failed": "Fix schema, name, category, or source."
    },
    "required_tool_shape": {
      "language": "python",
      "entrypoint": "def run(...) -> dict",
      "schema": "strict JSON object schema",
      "output": "JSON-serializable dictionary",
      "persistence": "Rust-Brain RBMEM"
    },
    "low_impact_categories": [
      "analysis",
      "debugger",
      "profiler",
      "refactor",
      "report"
    ],
    "high_impact_categories": [
      "filesystem",
      "memory",
      "shell",
      "web_bubble"
    ]
  }
[END SECTION]

[SECTION: rbforge.agent_setup.review_policy]
type: hermes:memory
graph:
  node_type: "policy"
  relations:
    - to: "rbforge.agent_setup.forge_protocol"
      type: "constrains"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  High-impact categories require review:
  - filesystem
  - memory
  - shell
  - web_bubble

  If a forged tool returns review_queued:
  - Do not run it automatically.
  - Report the section path and reason.
  - Wait for explicit human approval or integration policy.
[END SECTION]

[SECTION: rbforge.agent_setup.minimal_instruction]
type: hermes:memory
graph:
  node_type: "agent_instruction"
  relations:
    - to: "rbforge.agent_setup.forge_protocol"
      type: "summarizes"
    - to: "rbforge.agent_setup.runtime_policy"
      type: "summarizes"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  Use RBForge for reusable missing capabilities. Before forging, prefer existing
  tools in tools.registry. When forging, provide a complete Python run(...)
  implementation, a strict JSON object schema, a category, expected output keys,
  and representative sample arguments if defaults are insufficient. Run a forged
  tool only when forge_tool returns status=registered. Treat filesystem, memory,
  shell, and web_bubble categories as review-required. Never forge tools that
  handle secrets, credentials, arbitrary shell execution, destructive file writes,
  or one-off work. Persist and inspect durable setup through Rust-Brain RBMEM.
[END SECTION]

[SECTION: rbforge.agent_setup.health_check]
type: hermes:memory
graph:
  node_type: "procedure"
  relations:
    - to: "rbforge.agent_setup.install"
      type: "verifies"
    - to: "rbforge.agent_setup.rust_brain"
      type: "verifies"
temporal:
  created_at: "2026-04-29T00:00:00Z"
  updated_at: "2026-04-29T00:00:00Z"
  expires_at: null
content: |
  Health check:
  - python -m compileall -q src tests examples scripts
  - pytest -q
  - rbmem validate memory.rbmem

  Then forge a small temporary tool against a temporary RBMEM file.
  If the tool registers and run_forged_tool returns ok=true, RBForge is ready.
[END SECTION]