🏷️ Owners of information
Fact, preference, hypothesis, decision. When you have three versions of the same information scattered across memory, CLAUDE.md and old sessions, which one counts? This module gives the answer: every kind of information has an owner, an origin, a date and an update rule. That is what lets the "brain" survive a model switch without turning into a mess.
🧩 The four types and why mixing them breaks things
Every piece of information living in your workspace is one of four types: a fact (something verified, with a source), a preference (how you like things to be done), a hypothesis (something that seems true, but nobody has confirmed) or a decision (an accepted choice, with context and consequences). The most common mistake among people who use agents is throwing everything into the same bag: Claude's automatic memory records "the user prefers X" next to "the server port is 8000" next to "I think the build broke because of the cache". Three different types, treated as equals.
Read each box top to bottom: the type, a real example from this course, who owns it, the rule that changes the information, and where it lives. Only the fact has a glow because it is the only one that requires a source; the hypothesis has a dashed border because it is provisional by definition.
New here? "Source" is where the information came from: a file, a command you ran, a page. A fact without a source is just a sentence someone wrote one day. "Provenance" is the technical word for this: the origin trail of a piece of data. We'll use it a lot in this module.
✓ Separated by type
- ✓A new agent knows what it can trust and what it needs to check.
- ✓A preference doesn't turn into a "truth about the world".
- ✓Hypotheses age out and get discarded without mercy.
- ✓Decisions have context: you can revoke them knowing why.
✗ Everything in the same bag
- ✗An "I think" from three months ago becomes a mandatory instruction.
- ✗The agent cites a guess as if it were a verified fact.
- ✗Nobody knows who is allowed to change what.
- ✗When you switch models, the noise migrates along with the signal.
Key concepts
Verified, with source and date. Changes only with a new source.
How the owner wants it. Only the owner changes it.
Provisional. Either becomes a fact or gets discarded.
An accepted choice with context and consequences.
📇 Origin, scope, date, status, update rule
Prompt B (the portable-workspace mega-prompt) requires every durable note to record five things: an ID, the scope (does it apply to this project? to this client? to everything?), the source, the observation date and the status (draft, accepted, revoked), plus a rule for when to review or expire it. It looks like bureaucracy. It isn't: it's the minimum needed for an agent that has never seen the project to answer "where did this come from and is it still valid?".
Sample durable note — the header that the kit's context/overview.md template already ships with
# Overview — agente-claude-codex
- ID: overview | Scope: this repo | Source: docs/ (3 texts + PDF) and local audit
- Observation date: 2026-09-13 | Status: accepted | Review when: Codex or Claude Code version changes
## Verified facts (2026-09-13)
- Codex CLI 0.154.0 has no `import` command; the "one-click" import belongs to the desktop app.
- polyskill 0.1.0 installed globally.
## Owner preferences
- Audit first, no bulk copying, secrets kept out.
## Hypotheses (unverified)
- The heuristic classification of 71 skills as "reusable" is correct for most; needs sampling.Notice that the same file has three separate sections: facts (with dates), preferences and hypotheses. An agent reading this knows exactly how much weight to give each line. And the "Review when" field says when the fact may have gone stale: when Codex changes version, the line about import needs to be checked again.
ID and scope
A stable name so other files can cite it, and the answer to "where does it apply?". A client fact never has global scope.
Source and observation date
Where it came from and when it was seen. "Observation date" is not "writing date": it's when reality was checked.
Status and review rule
Draft, accepted or revoked. And the review trigger: a date, or an event ("when Codex updates").
New here? "Scope" is the reach of a piece of information: global (applies to you in any project), project (applies only here) or client (applies only to that client). Mixing up scope is like putting a client's password in the general rules file: the right information, in the wrong place, becomes a problem.
Key concepts
Information that outlives the session and needs metadata.
When reality was checked, not when the text was typed.
Draft, accepted, revoked. Tells you whether to trust it.
The trigger that forces you to re-check the fact.
⚖️ Provenance beats timestamp
When two versions of a piece of information contradict each other, the instinct is to keep the most recent one. Prompt B forbids exactly that: resolve conflicts by provenance and accepted decision, not by "which timestamp is newer". Why? Because the newer version may be a guess from a rushed session, and the older one may be a verified fact with a source. Write date does not measure reliability.
The version on the left is older and wins because it has a source and accepted status. The one on the right is newer and loses: without a source, it is a hypothesis. It receives superseded_by and becomes dashed, but it is not deleted.
🔬 How openpcbotv3 actually does this
The v3 bot on this machine has a nightly memory consolidation. It merges duplicates and, when it detects a contradiction between two memories, the old one receives superseded_by pointing to the new one, and is never deleted. The same mechanism works the other way around: if the "new" one is the loser, it is the one that gets the mark. The point is that nothing disappears; only what is in force changes.
- •Deleting destroys the trail. You lose the "why we thought that".
- •Hiding preserves the trail and keeps only one version active.
- •Backup before every consolidation round, because a mistake here erases context.
New here? A "timestamp" is the date-and-time stamp of when something was recorded. "Superseded" is the state of a piece of information that has been replaced by a more reliable one. Keeping the superseded one with a pointer to the winner is what makes it possible to reconstruct the history later.
Key concepts
The origin trail. Decides who wins a conflict.
Beats any version without acceptance, new or old.
Marks the version that lost, without deleting it.
Recent does not mean correct.
⬆️ Promoting a fact: from raw memory to approved overview
Claude Code writes memory on its own: on this machine there are 869 files in 227 folders. None went through approval. That is not a source of truth; it is raw material. Prompt B says "deliberately promote verified facts from native memory or from conversations". Promoting is the conscious act of taking a line from raw memory, verifying it, giving it a source and a date, and only then writing it into context/overview.md as an accepted fact.
Raw memory written
The agent wrote "the user uses flux2-klein by default" in some random session. No source, no date.
Proposal
When touching the project, the agent proposes: "this looks like a stable preference; promote it to the overview?"
Verification and human approval
You confirm (or correct: "it's a preference, not a fact"). It gains a source ("global rule in CLAUDE.md"), a date and accepted status.
Written in the right place
It goes to the correct section of the overview. The raw memory keeps existing as evidence, kept separate.
🗃️ The openpcbotv3 vault: "the bot proposes, you approve"
The v3 bot keeps two curated files, ~/vault/MEMORY.md and USER.md. The bot proposes entries; nothing is written without your approval. USER.md goes into every prompt. It is the same promotion idea, already running: the database's automatic memory is raw material; the vault is the approved overview. This machine's migration plan uses that vault as the global overview of personal facts.
In Track 3, Project 3, you connect Claude, Codex and dsh to read the same USER.md.
✓ Promote
- ✓One fact at a time, when touching the project.
- ✓With verification and human approval.
- ✓Gains an ID, scope, source, date, status.
- ✓Raw evidence preserved separately.
✗ Bulk copy
- ✗Dumping the 869 memory files into
context/. - ✗Carrying guesses, duplicates and dead facts along with it.
- ✗No source: the new agent doesn't know what to trust.
- ✗Claude's noise becomes Codex's noise.
Key concepts
Native memory and sessions: evidence, not source.
A deliberate act of verifying and recording with metadata.
The agent suggests, the human decides. Nothing automatic.
MEMORY.md and USER.md: the approved overview of openpcbotv3.
🔁 Indexes rebuildable from the sources
Semantic search, embeddings, vector databases, summary caches: all of that is an index, and an index is derived. Prompt B closes the ownership section with a simple rule: "make search indexes rebuildable from the source records you own". If the index gets corrupted, or you switch tools or embedding models, you run the build again and it comes back. If the only copy of the information lives inside the index, you've lost it.
📊 Real examples from this machine
- •openpcbotv3:
bge-m3vectors are reindexed by cron every 15 min from the memories table. Deleting the index loses nothing. - •INEMA catalog:
courses.data.json,cursos.json,base.jsonare all generated. The source iscourses.tsandPortal.tsx. Editing the generated file by hand is the mistake the portal skill forbids. - •Migration kit:
relatorios/auditoria-*.mdis generated byaudit.sh. Run it again, it's rebuilt.
New here? An "embedding" is a way of turning text into numbers so a program can find similar texts. An "index" is any structure built to find things faster. Both are transformed copies of the original. Rule of thumb: if you can't delete it and regenerate it, it's not an index, it's a source in disguise.
⚠️ The mistake to avoid
Letting the agent's memory live only in a proprietary vector database. Switch models, and the old embedding is useless. Switch tools, and the database won't open. Without the source in Markdown, the "brain" disappears along with the model. It's the opposite of what this course teaches.
Key concepts
Source is what you edit; derived is what the build generates.
Delete and regenerate without loss. The definitive test.
Search, vectors, cache. Always derived.
Opens anywhere, with any model.
🔐 Secrets and raw material stay out
Two kinds of content never enter the portable core: secrets (API keys, tokens, passwords) and raw native state (JSONL sessions, Claude's memory database, entire chat exports). The mega-prompts repeat this in almost every section: "keep secrets and raw private memory out of reports and repositories", "preserve raw evidence separately". The portable core is what you would publish; everything else stays where it is, referenced, never copied.
✓ Goes in the core
- ✓The rule "keys live in
~/projetos/openpcbotv2/.env" (the reference). - ✓Promoted facts, decisions, tasks, handoffs.
- ✓The name of the registered MCP (magnific, metricool).
- ✓A curated, dated snapshot of context.
✗ Stays out
- ✗The value of the key (never printed, never copied).
- ✗The 2.3 GB of Claude JSONL sessions.
- ✗The
~/.claudeor~/.codexfolder copied in full. - ✗Third-party material without a license (the kit's
docs/was kept out of git for this reason).
🧭 The dsh-sandbox case
The ~/projetos folder on this machine holds 269 secret files. That's why dsh-sandbox ties mount and provider together: local mode mounts the projects but only talks to Ollama; remoto mode talks to OpenRouter but can't see the projects. Combining the two requires typing "CONFIRMO". It's the rule of this topic turned into a mechanism: the secret may exist on the machine, but the executor that talks to the outside can't see it.
New here? "Raw evidence" is the original, untreated material: the full transcript, the complete log, the chat export. It's valuable for auditing later, but it's not meant to be read in every session. It stays archived, with a pointer in context/sources.md saying where it is and when it's from.
Key concepts
The core says where the key is, never what it is.
Sessions and automatic memory stay where they were born.
An approved excerpt, with source and date, instead of the raw material.
If it can't go into a repo, it's not in the core.
Self-check (optional): two notes contradict each other. The August one says "port 8000" with a source; the September one says "I think it's 8080" with no source. Which one wins?
🎯 Module summary
Next module:
1.6 — Audit before implement: analyze → plan → simulate