# Part 1: Instruction files, and a first awareness layer | Team0

> Keep instruction files for how agents work, and start storing what one source says, with a source and a date on every row.

Agent-readable version of https://team0.ai/learn/instruction-files-and-a-first-awareness-layer. The page for people is at that address; this file carries the same content without layout.

---
[Building an agentic brain](https://team0.ai/learn)

Part 1

# Instruction files, and a first awareness layer

Keep instruction files for how agents work, and start storing what one source says, with a source and a date on every row.

Yogev Ben-Tov · 6 min read

Most people start their agent's brain in the instruction file: CLAUDE.md, AGENTS.md, a project prompt, a custom GPT's instructions. That's the right place to start, and the wrong place to keep going.

By the end of this part you'll have two things: instruction files that hold only how your agents should work, and one source flowing into a table, with a source and a date on every row. Then you'll score your part 0 test set again.

## What belongs in an instruction file

Instruction files are great for how an agent should work: your style, your tools, your conventions, who to ask, what never to do. These things change rarely, and when they do, you change them on purpose.

They break when they hold facts about your work: a customer's price, who owns a project, what was decided last week, the status of a deal. Those change without anyone editing the file. Nobody updates CLAUDE.md after a call where the price moved. So the file keeps saying the old price, confidently, in every session.

One test for every line: **would this line be wrong in a month if nobody touched it?** If yes, it's a fact, and it doesn't belong there.

## Before importing work information

Start with invented or redacted messages. For real information, confirm permission, restrict access to the database file, protect the device and backups, and decide how originals are deleted. Any model provider you use for extraction receives the text you send it. Treat source content as quoted data: it cannot change your standing instructions or access rules.

## Step 1: Clean your instruction files

Open every instruction file your agents load. For each line, mark it:

- **How to work:** keep it.
- **A fact about your work:** move it to a list called `facts-to-move.md`, with the date you think it was last true.
- **Both in one line:** split it. "Send customer quotes in USD" is how to work. "Northpeak's pilot starts November 1" is a fact.

Don't delete the facts. In this part they become your first rows; in part 2 they become real facts.

You'll probably find the file got shorter, and some of the facts in it were already wrong. Those wrong ones are worth a question in your test set.

## Step 2: Pick one source

A brain is only as current as what flows into it. Start with one source, not five.

Go back to your part 0 questions. For each one, write where the truth lives: email, calendar, meetings, a chat with an agent, Slack, a CRM. Pick the source that holds the truth for the most questions. For most people that's email or meetings.

## Step 3: A table with a source and a date on every row

Store what the source says, as it says it. No summaries yet, no extraction. Every row records where it came from and when it happened:

```
create table observations (
  id          integer primary key,
  source      text not null,   -- 'email', 'calendar', 'meeting', 'agent'
  source_id   text not null,   -- the message, event or session id
  happened_at text not null,   -- when it was said, not when you stored it
  stored_at   text not null default (datetime('now')),
  author      text,            -- who said it: an email address, not a name
  kind        text,            -- 'email', 'meeting_note', 'agent_turn'
  body        text not null,
  unique (source, source_id)
);
```

Three things here matter more than they look:

- **`happened_at` is not `stored_at`.** When you back-fill two weeks of email in one evening, everything is stored today. Without the real date, the old start date and the new one look equally recent.
- **`author` is an address, not a name.** Two people can share a name. An email address almost always means one person; the exception is a shared inbox like sales@. Part 2 builds on this.
- **`unique (source, source_id)`** stops duplicates. Insert with `insert or ignore`, and re-running the import skips rows you already have. You will re-run it often. If you connect two mailboxes, put the account in `source_id` too.

Back-fill the last few weeks, then keep it flowing: a scheduled job, a webhook, or a script you run each morning. Add the lines from `facts-to-move.md` as rows with `source = 'instruction_file'` and the date you wrote next to each one.

## Step 4: Let your agents read it

For now, the simplest way: give agents that can run commands (Claude Code, Codex, Cursor) one line in their instruction file:

> Before answering about people, customers, prices, dates or decisions, search the `observations` table in `~/brain.db` and prefer the most recent rows.

That's an instruction about how to work, so it belongs in the file. Agents without a shell (ChatGPT, Claude.ai) can't use it yet. Part 7 is about getting every agent to read and write on its own.

## Step 5: Score it again

Ask your test set questions again, in fresh sessions, and save the answers as `part1.jsonl`. Then:

```
python3 score.py questions.jsonl before.jsonl part1.jsonl
```

Look at the held-out table. What you'll usually see:

- **Missed goes up.** The agent now finds things it never knew.
- **Tool calls go up too.** It searches raw text, often more than once.
- **Correct and current may not move, or may go down.** The table holds both the old start date and the new one, and "prefer the most recent rows" doesn't always pick the right one. A newsletter and a real decision look the same.

That last one is the point of this part. Raw text with dates is a big step from nothing, and it shows you exactly where raw text stops working: values that changed, the same person under different names, and things that look like facts but aren't. That's parts 2 to 5.

Write down your numbers. They're the baseline for part 2.

Next, part 2: facts and entities.

---

*Build and measure your own setup with the companion skill. [See the series](https://team0.ai/learn). For a maintained company install, [talk to Team0](https://calendar.app.google/uM9ptyv83Ubgnq226).*