thebrain-ingest

Breaking material down into TheBrain

The job is not "store the text" but graft meaning into the existing graph so that six months from now it can be found, and is already connected to whatever arrives later.

Fifteen thoughts dangling under a single article is a bad outcome, even if every one of them is accurate.

Order of work

1. Find out where you are landing

brain_list                      → which brain, is the index ready
brain_list_types_and_tags       → the conventions this brain already uses

If the index is not ready, brain_search will say so. Tell the person — without an index, finding existing material works worse and the risk of duplicates goes up.

2. Extract the concepts, then search for each one

Read the material and write out the concepts — what it is actually about. Then search for each of them:

brain_search { query: "<concept>", variants: ["synonym", "translation", "broader term"] }

Variants are mandatory. Without an index, search runs on them alone; with an index, they still raise recall.

If something close turns up, do not create a new thought. Extend the existing one and link to it. This is the whole difference between a second brain and a folder of files.

3. Look at the neighbourhood of your attachment points

brain_traverse { thoughtId: "<what you found>", depth: 2 }

This shows which area has already taken shape and what naming conventions hold there. Graft into the existing structure, not alongside it.

4. Assemble a plan and write it in one call

brain_ingest { thoughts: [...], links: [...] }

Do not create thoughts one at a time. Fifteen thoughts means fifteen calls plus links plus notes — minutes of work, and a failure halfway through.

Give the top thought of the plan a parent. Sent a second time, a plan finds each thought next to its parent and creates nothing twice; a thought with no parent it cannot find, and creates again with everything under it.

Send one plan at a time, and wait for its result before the next. Two brain_ingest calls sent at once do not see each other's thoughts, and a thought both of them name is created twice.