brain-learning · diff
git:20261030.5c2b770 to git:20261102.be5c19e
75 added, 66 removed. Audit A to A.
---
name: brain-learning
- description: Use when material, structured entity notes, or a thought must become durable memory, and when a remembered fact or page prose turns out wrong — learning an article, page, paper, book, file, recording, or meeting transcript; curating an entity, project, or concept page; capturing someone's own idea; repairing memory after a correction. Read this before the first learn_source or put_page call in a conversation. Routes each material kind to the right learning path, guides the audience scope choice, and owns the write and repair discipline.
+ description: Use when material, structured entity notes, or a thought must become durable memory, and when a remembered fact or page prose turns out wrong — learning an article, page, paper, book, file, recording, or meeting transcript; curating an entity, project, or concept page; capturing someone's own idea; repairing memory after a correction. Read this before the first knowledge-page write in a conversation. Routes each material kind to the right learning path, chooses a page with the intended audience, and owns the write and repair discipline.
default_enabled: true
ankole-runtime: main
---
# Learning material into the Brain
- `learn_source` registers one web address as a Brain learning source and starts
- a background learning run: the system fetches the page, stores it as a memory
- page, splits it for search, and extracts durable facts. The knowledge becomes
- recallable for everyone inside its audience scope. You do not fetch, chunk, or
- file anything yourself.
+ 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
| Material | Path |
| --- | --- |
- | One public web page, article, paper, or post | `learn_source` with its url |
- | Several specific pages | One `learn_source` call per url |
- | A whole site, feed, or archive | Not supported as one action. Learn the specific pages that matter, or tell the user a site-wide import is not available yet |
- | A book or local text file | Operator import: an admin registers a file source in the Console. Tell the user that, and name the file |
- | A PDF, EPUB, or image | No direct learning path. A Background Agent Job with the `pdf` or `ocr` Skill extracts the text; then route the text — operator import for a durable source, `remember` for the few conclusions that matter |
- | An audio or video recording | No learning path; the system does not transcribe. Ask for the transcript or notes, then route those as text |
- | A meeting transcript or notes | Pasted into the conversation it is learned automatically; as a file it goes through operator import. `remember` each decision and commitment that matters, with the spoken words as provenance |
- | Text pasted into this conversation | Nothing. Conversations are learned automatically; do not re-save them |
+ | One public web page, article, paper, or post | Read it with the available web tools, then save the relevant material and its source link in a knowledge page |
+ | Several specific pages | Read the pages that matter and save their evidence with clear source attribution |
+ | A whole site, feed, or archive | Select the specific pages that answer the request, or use a background research job to collect them; do not claim a site-wide import |
+ | A book or local text file | Read the text in a Background Agent Job, then save the requested material or conclusions in knowledge pages |
+ | A PDF, EPUB, or image | A Background Agent Job with the `pdf` or `ocr` Skill extracts the text; save the useful source material and `remember` the conclusions that matter |
+ | An audio or video recording | Use an available transcription tool; if none is available, ask for the transcript or notes and route those as text |
+ | A meeting transcript or notes | Read the transcript, then `remember` each decision and commitment that matters, with the spoken words as provenance; save a page when the person wants a durable document |
+ | Text pasted into this conversation | Conversations are learned automatically; do not duplicate the transcript merely to make it searchable |
| Someone's own idea, thesis, or framework | `remember` — see "Capture ideas verbatim" |
- | One fact, decision, or preference | `remember`, not `learn_source` |
- | A structured page or dossier for a durable entity, project, or concept | `put_page` for a new page (linking related pages via `[[slug]]`), or `get_page(include_content: true)` followed by `edit_page` when the page already exists |
- | Revising or updating prose on an existing page | `get_page(include_content: true)` to read `content` and `revision`, then `edit_page` with `expected_revision` |
- | An open question that needs investigation and a report | A background job or deep research; afterwards `remember` the durable conclusions or curate a page with `put_page` / `edit_page` |
+ | One fact, decision, or preference | `remember` with `claim` and `provenance` |
+ | A structured page or dossier for a durable entity, project, or concept | Resolve the entity first; update its existing knowledge page, or use `pod_create_page` under the intended parent |
+ | Revising or updating prose on an existing page | Read with `pod_get_page` at `level: "L2"`, then use `pod_save_page` with the returned `revision` as `base_revision` |
+ | An open question that needs investigation and a report | A background job or deep research; afterwards `remember` the durable conclusions or save the requested report in a knowledge page |
- ## Choose the audience scope
+ 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.
- Omitting `scope` uses this conversation's audience: the asker in a DM, the
- member group in a group chat. That default is right for most requests — the
- person who asked can recall what was learned.
+ ## Choose the page and its audience
- Pass `scope: "world"` only when both hold: the material is public, and the
- requester wants the whole deployment to know it ("让大家都学一下" is world;
- "帮我读一下这篇" is not). Pass a `group:<name>` scope to learn for one team
- you belong to. When one request mixes audiences, learn the source at the
- narrow scope and `remember` the shareable conclusions separately.
+ Use `pod_list_pages` to find the destination. Omitting `id` lists the shared
+ Space roots, including AnkoleBrain; passing a page or folder UUID lists its
+ visible children. 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 attach the claim to the
- existing page; a name that does not resolve files the claim to the channel
- instead.
- - Prefer surgical edits over full-page overwrites. Before updating an existing
- page, call `get_page` with `include_content: true` and pass its `revision` as
- `expected_revision` to `edit_page`. Reserve `put_page` with
- `expected_revision` for full-body replacements on single-scope pages, and link
- related entities inline with `[[slug]]` wikilinks so graph traversal and
- recall discover the edges.
+ 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 page, `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.
- Transcripts and recorder summaries carry claims, not facts. Transcription
garbles names, and machine summaries turn banter into commitments. Before
- you remember a surprising claim — a role change, an ownership, a major
- event — find the words that state it, and `recall` what memory already
- holds. When the new claim contradicts established memory, do not overwrite;
- surface the conflict.
+ 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.
- - Learning is asynchronous. Do not describe or quote the material as learned
- in the same turn; say the learning run started. In a later turn, `recall`
- brings the content back.
- - The same url registers once. Repeating the call reuses the source and
- re-runs learning, which picks up changed content. The reported
- `audience_scope` is the one that actually applies.
- - A paywalled or login-walled page cannot be learned. Never work around an
- access wall; report the block and ask for an accessible copy.
- - Never invent what a source contains. Before the learning run completes you
- know the url, not the content.
+ - 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
- The direct fix is standing duty: `remember` the correction — a close match
- supersedes the stale claim — otherwise `recall` the stale claim and `forget`
- it by claim id. A wrong claim rarely lives alone, so after the direct fix:
+ 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:
- - Check propagation. `recall` the wrong phrasing and its variants, and fix
- every claim that repeats the error, not the first one found.
- - A fact attached to the wrong person has two homes to check: remove it where
- it does not belong, and record it where it does.
- - A confabulation has no stored source to fix. `remember` the correction with
- the mistake named in `context`, so recall surfaces the guard next time.
- - When wrong prose sits inside a page body rather than a structured claim, read
- the page with `get_page(include_content: true)` and patch the exact span with
- `edit_page` under `expected_revision`.
+ - `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` or `get_page` to read the learned knowledge, `synthesize` when a
- question needs conclusions, contested points, and open gaps drawn across many
- memories, and `remember` or `edit_page` for your own durable judgments and
- curated notes about the material.
+ 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.