Hizal Write#

Write as you build. Not optional.

Available Write Tools#

What you're writingToolScopePersonal observation or lesson learnedhizal__write_memoryAGENTArchitecture or design decisionhizal__write_knowledgePROJECTConvention this codebase followshizal__write_conventionPROJECT (auto-inject)Agent identity or personalityhizal__write_identityAGENT (auto-inject)Org-wide knowledgehizal__write_org_knowledgeORGPrinciple (requires human promotion)hizal__store_principleORGCustom chunk typehizal__write_chunkvaries

Do not use hizal__write_context — it's deprecated. Use the purpose-built tools above.

Custom Chunk Types via write_chunk#

For chunk types not covered by the built-in tools, use hizal__write_chunk. Chunk types are customizable per org — always discover what's available before assuming a type doesn't exist.

Discover Available Types#

text

hizal__list_chunks()  # inspect chunk_type values in results

Or check the project's AGENTS.md for the org's type conventions.

Usage#

text

hizal__write_chunk(
  type="<chunk-type-slug>",
  query_key="<unique-key>",
  title="<short title>",
  content="<full content>",
  scope="PROJECT",  # or AGENT, ORG
  project_id="<id>",  # required for PROJECT scope
  org_id="<id>",  # required for ORG scope
  agent_id="<id>"  # required for AGENT scope
)

write_chunk accepts the same common fields as all other write tools (query_key, title, content, gotchas, related, source_file, inject_audience, etc.). It also accepts custom_fields for type-specific metadata.

When to Use write_chunk vs Built-in Tools#

• Built-in tools — use whenever the content maps cleanly to MEMORY, KNOWLEDGE, CONVENTION, IDENTITY, ORG_KNOWLEDGE, or PRINCIPLE
• write_chunk — use for any custom org type (e.g., SPEC, RUNBOOK, ADR, INVESTIGATION)
• When in doubt, check what chunk types the org has defined and pick the closest match

Write One Chunk Per Decision#

Don't batch everything into one chunk at the end. Write as you go:

• Made an architecture decision? → write_knowledge now
• Learned a codebase convention? → write_convention now
• Discovered something useful personally? → write_memory now
• Found a custom type that fits better? → write_chunk now

Common Fields#

All write tools accept:

• query_key — unique key for this topic (enables exact lookup later)
• title — short descriptive title
• content — the full context content
• source_file / source_lines — where this came from
• gotchas — list of warnings or pitfalls
• related — list of related query_keys
• inject_audience — DNF targeting spec for auto-injection (omit for defaults)

Example#

text

hizal__write_knowledge(
  project_id="<id>",
  query_key="nuvei-webhook-signing",
  title="DMN Webhook Signature Verification",
  content="All DMN payloads are verified using SHA-256 HMAC. The checksum is computed from sorted key-value pairs + merchant secret. See package internal/checksum for implementation.",
  related=["nuvei-payload-structure", "merchant-credentials"],
  gotchas=["Never use /payment for credential verification"]
)

Promote AGENT → PROJECT#

If a personal memory chunk is broadly useful for the team, promote it:

1. Read the chunk with hizal__read_context
2. Write it back as write_knowledge or write_convention with the content
3. Optionally delete the original AGENT chunk with hizal__delete_context