agentbull/ankole/brain-learning

Learning material into the Brain

Pod knowledge pages hold the source text and curated notes. Brain retrieves those pages, their relationships, and atomic claims. Save prose with the Pod page tools and record a specific fact or judgment with remember.

Route the material first

For a source that needs ongoing synchronization, an operator can register its URL or file in the Console's Sources view. A one-time reading and page save does not require source registration.

Choose the page and its audience

Use pod_list_pages to find the destination. Omitting id lists the shared Space roots; passing a page UUID lists its visible children. Use brain to discover organizational knowledge and write_object to create or revise Brain objects. A new page inherits its parent's access. Choose the existing team, entity, or conversation page whose readers match the request. Public source material alone does not authorize sharing private analysis with a wider audience.

For remember, omitting source_node_id uses the current conversation's source page. Pass another source page UUID only when its audience fits the claim. A claim's entity identifies its subject; source_node_id determines who can retrieve its evidence. When a request mixes audiences, keep the source material on the narrower page and record shareable conclusions on the appropriate shared page.

Capture ideas verbatim

A person's original thinking is the highest-value material, and their exact wording is the signal. When someone states an idea, thesis, or framework worth keeping — typed, spoken, or in a transcribed voice note:

• remember it with the person's own words in provenance, not a flattened

paraphrase. The claim states the idea; the provenance quotes it.

• Choose the kind by nature: belief for a held position; take, bet, or

hunch for a judgment or prediction, with the author as holder.

• One atomic claim per call. A voice note that covers an idea and a person

becomes two claims.

Write discipline

• Resolve the entity before you write. When a claim is about a named person,

company, or project, check entity first and use the returned page UUID in remember.entity. Resolve ambiguity before attributing a claim.

• Read the whole page before changing it: pod_get_page takes id and

level: "L2", and returns body, metadata, revision, and visible children. Preserve unrelated prose and YAML frontmatter. Make the intended edit, then submit the complete Markdown through pod_save_page with id, base_revision, and markdown. A revision conflict means read again and reconcile the change.

• For a new Brain object, write_object takes category, title, and complete

markdown. For a child of an existing knowledge object, pod_create_page takes parent_id, title, and complete markdown. Keep the returned id for later reads and writes. Link related pages using Markdown links whose target is ankole:page/ followed by the actual page UUID, so graph traversal can follow their identities.

• Shared rules belong on their shared knowledge page. If the Agent cannot

edit it, propose a pod.knowledge.save action card in a native Pod room, with the page ID, complete draft, and captured base revision. The owner reviews the diff before confirming. In external IM, provide the draft and page link for an authorized owner to review and save in Pod. For a new Brain object without creation permission, propose brain.object.create in a native Pod room with the category, title and complete Markdown draft.

• Transcripts and recorder summaries carry claims, not facts. Transcription

garbles names, and machine summaries turn banter into commitments. Before remembering a surprising claim — a role change, an ownership, a major event — find the words that state it and recall what memory already holds. Surface a contradiction rather than silently choosing a version.

• A speaker or attribution you cannot resolve stays unwritten. A wrong

attribution is worse than none.

• A successful page save confirms the document revision. Automatic fact

extraction runs asynchronously; do not claim those facts have been learned until retrieval confirms them.

• If a source requires access you do not have, report the block and request

an accessible copy. Never invent what the source contains.

Repair wrong memories

Record the correction with remember, including the evidence and the mistake in context. A matching stale claim can be superseded by the new fact. Then check propagation:

• recall the wrong phrasing and its variants, and correct every repeated

claim supported by the evidence.

• For a fact attached to the wrong person, inspect both people before

recording the corrected attribution.

• If a stale structured claim remains active, identify it by claim ID for

review in the Console; do not report it as removed.

• When wrong prose sits in a page, read its full content, correct the relevant

span, and save the complete document under its captured base_revision. Preserve unrelated content and metadata.

After it lands

Use recall for evidence and pod_get_page for the complete source page. Use entity for current claims, timeline, relationships, and visible child pages, and synthesize when a question needs evidence connected across many memories. Record your durable judgments with remember and maintain curated prose with the Pod page tools.