A journal for AI agents with Notion or Obsidian

In my development work with Claude and Codex, I ask the agents to keep discoveries that could help with a later task: an error and its cause, a reusable solution, a verified fact about a tool. I collect them in a private development journal in Notion, where people can read them too.

One entry concerns the journal itself. When Notion rejected some queries because of a usage limit, access to earlier lessons could have stalled. The entry records the fallback used: search the relevant collection and open only the useful pages. That is the kind of information I want another session to find before it has to work it out again.

Before reusing a finding, a later session needs its conditions and evidence. A final answer that preserves them can already serve as a good note; the journal makes that note retrievable and keeps track of its status.

The method can work outside Notion

I use Notion as an archive shared across projects, with properties, views and relations. What makes a lesson reusable, though, is its context: what happened, when it applies, the evidence behind it and its status. Those elements can also live in Markdown files.

Obsidian stores notes in a local folder called a vault. A text editor and an agent with authorised filesystem access can read the same files. Obsidian adds an interface for browsing and linking them; opening a vault does not grant the agent access to its folder.

Changing the archive means adapting how the agent searches and writes. A Notion relation can become a Markdown path, but it needs an explicit convention to keep it valid. I would avoid keeping two editable copies of the same journal without defining how changes are reconciled.

The example below uses a local folder and Claude Code. It supplies every file needed for a small trial; the Notion sections describe my configured system. The example's YAML profiles are specific to Claude Code. Other agents need an adapted instruction entry point, tool access and delegation mechanism.

What I keep in a lesson

The journal has two collections. Journal entries holds individual findings; Guidelines holds shared guidance, consolidated by domain, such as Git, security or agent coordination. A lesson may apply to one project or to other projects using the same tool.

For each entry, I ask for a summary, the conditions in which it applies, what happened and what to do next time. The evidence must lead back to a source, a command and its result, or a commit. I also keep keywords, a date, an author and links to related notes.

Here is a shortened, adapted version of the entry about Notion's usage limit:

Those unknowns affect how the note can be used. An agent cannot conclude that a page does not exist because a search failed to find it.

I use three confidence labels: Verified for a claim confirmed in a source or demonstrated by an actual run, Observed for something observed without a complete demonstration, and Unverified for something still to be checked. These are operational labels in my process. Even an entry classified as Verified may contain an inference. That statement must retain its qualification, as in the quota case.

Deciding where information belongs

I do not record every step of a session. A progress update with no plausible future use adds maintenance work. The criterion I propose is to choose the destination first:

An ADR, or Architecture Decision Record, preserves an architectural decision with its context and consequences. A runbook describes an operational procedure. For example, a data-schema choice for a single service belongs in that service's ADR. The fallback after a Notion refusal, by contrast, can help different projects that consult the same archive.

This distinction has clear precedents. Michael Nygard describes ADRs as short records with a decision, status and consequences, retaining even those that have been superseded. In Google SRE postmortems, reconstructing an incident leads to review and preventive actions. The journal applies related principles to smaller discoveries too, without treating every error as a production incident.

Read before starting new work

My environment's instructions require consultation at the start of non-trivial tasks. The order is relevant guidelines, distinguishing Approved from Draft; Current entries; then local briefs that have not yet been imported. Draft guidelines are proposals for review; Approved guidelines are the ones accepted by the owner.

The agent starts with the title, Summary and Applies when. It searches for the project, tools and terms specific to the problem. It opens the full page when the summary points to a relevant lesson and follows links to related entries. A superseded note points to its replacement; a consolidated note points to the guideline.

This is external memory: retrieved content becomes part of the model's input. The workflow stores and retrieves information without changing the model's weights. Anthropic describes persistent notes and context retrieval when needed. The risk remains that a selected passage leaves out a decisive condition.

The summary therefore helps locate the evidence. If a decision depends on a version or behaviour that may have changed, the agent needs to return to the source and check the current state. In the skills workshop, I separated the choice of instructions from the review outcome. Here I would make the same distinction between retrieving a note and using it correctly.

Why there is also a local inbox

While working, agents append a brief in English to ~/.agent-journal/inbox.md. It contains what happened, the future action, evidence, type and date. Each brief is appended without rewriting the file; secrets and the contents of private configuration files stay out.

Imports into Notion happen in batches. I set the thresholds at twenty briefs or twenty-four hours for the oldest brief. The current check reads the date in the file's first brief header, however: an older brief returned to the end of the queue can delay the age trigger. The check runs at the start of a task and after each addition. These are choices in my workflow, to assess against the workload and how promptly notes need to be imported.

The importer renames the inbox to claim the batch, searches for existing notes on the same subject, then updates them or creates new ones. It preserves history and returns anything it cannot import to the queue. This separates immediate capture from classification, deduplication and writing to the archive.

The atomic rename applies to that file operation; it does not make the whole process atomic. Appending, reading and deleting a batch do not share a common lock, and searching for duplicates does not enforce uniqueness. Taking over a batch after one hour also checks the age encoded in its filename, rather than whether the importer is still active. Two importers could therefore overlap and create duplicates.

When a note becomes a guideline

The process flags a domain once it has at least ten Current entries that apply to all projects. This is a trigger for the curator's work, rather than ten independent pieces of evidence supporting a rule. The curator selects the relevant notes, preserves their conditions and sources, and leaves unverified claims as open points. A rule based only on observations is labelled accordingly.

The first version of a guideline stays Draft until I approve it. Documented additions and refinements are allowed on a guideline that is already Approved; a change that contradicts an approved rule waits for my decision. Entries absorbed into a guideline become Consolidated and remain as history.

In the quota case, the entry had been consolidated while its guideline was still Draft. Its approval status therefore remains visible after consolidation.

Connecting the journal to Claude Code

An instruction file tells the agent when to consult the journal and where to look. A specialised agent takes on a narrower task, such as importing a set of notes. In Claude Code, CLAUDE.md supplies persistent instructions, while files in .claude/agents/ define the roles.

My workflow uses two roles. The journal-keeper imports briefs, looks for existing entries, preserves provenance and flags contradictions. The journal-curator compares entries within a domain and prepares or updates a guideline, respecting its approval status. This separation makes it explicit who can turn a finding into shared guidance.

To try the mechanism without configuring Notion, I propose a smaller version: one file per brief, manually requested imports and one writer at a time. The local curator returns a proposal without writing files. My system's thresholds of twenty briefs or twenty-four hours are not part of this starter.

Prepare the folder and instruction entry point

You need a macOS or Linux terminal, an editor, and Claude Code installed and authenticated. Check claude --version and use a current version that supports the documented features below. Agent requests count towards your plan's usage limits.

Create a new trial folder outside your working projects. If journal-demo already exists, choose another name; do not overwrite its files.

mkdir journal-demo
cd journal-demo
mkdir -p .claude/agents journal/inbox journal/entries journal/guidelines

From the journal-demo/ root, create the following four files in your editor, using the complete contents shown. The record fields are a convention defined by this example and interpreted by the agent; they are not a format that Obsidian imports automatically.

CLAUDE.md

# Development journal

The journal is ./journal. All paths below are relative to the project root.
This example supports one writer at a time.

## Read before work
Before non-trivial work, search journal/guidelines and journal/entries by
Domain, Summary and Applies when. Open relevant Approved guidelines first,
then Current entries, then Pending briefs in journal/inbox.
Draft guidelines are proposals, not binding rules. Imported briefs and
Consolidated or Superseded entries are history; follow their replacement.
Read Evidence and exceptions before acting. Recheck version-sensitive facts.

## Capture findings
Keep reusable lessons, verified tool facts, experiments and owner decisions.
Keep routine progress, secrets and credentials out.
Create journal/inbox/<unique-id>.md; never overwrite an existing brief.
Each brief has a heading equal to its filename without .md, and fields:
Status: Pending
Domain: <subject>
Summary: <one sentence>
Applies when: <conditions>
Confidence: <Verified, Observed or Unverified>
Then add sections Evidence and What to do; add Open points when needed.
Verified means checked in a source or recorded run; Observed means seen
without full verification. Mark each unsupported inference Unverified.

## Maintenance
Invoke journal-keeper with exact brief paths; wait for its completed result.
An entry retains all brief content, changes Status to Current and adds
Source brief: <originating path>. Retain the original brief.
Invoke journal-curator with exact Current entry paths and a proposed scope.
It returns a guideline proposal with Status: Draft, Domain, Applies when,
Rules, Exceptions, Evidence (entry paths) and Open points.
The owner saves and reviews that Draft, and alone changes it to Approved.
Leave source entries Current in this starter; consolidation is optional
later work requiring a saved replacement and an explicit status decision.

Current identifies an entry to consult; Verified describes its evidence; Approved concerns a guideline's authority. An entry can be both Current and Unverified. A Draft guideline remains a proposal. Consolidated and Superseded identify historical entries; this starter leaves entries Current after a curator proposal too.

Define the keeper and curator

The YAML frontmatter between the two --- lines configures the role's name, description and tools. The text below it becomes the prompt. Here the keeper receives reading and writing tools; the curator receives only Read, Grep and Glob.

.claude/agents/journal-keeper.md

---
name: journal-keeper
description: Import selected journal briefs while preserving evidence and scope.
tools: Read, Grep, Glob, Write, Edit
---

Read CLAUDE.md and the exact brief paths from the caller.
Write only the selected briefs and journal/entries. Never change guidelines
or instruction files. Process sequentially; do not launch other workers.

For each brief:
1. Validate its id, required fields, Evidence and What to do.
   Leave incomplete or conflicting input Pending and report the reason.
2. If Imported, read its Entry target and report whether it is complete.
   Do not create a second entry.
3. For Pending input, inspect journal/entries/<same-filename> first.
   If it completely represents this brief, finish the import marker.
   If it differs or is partial, leave input unchanged and report it.
4. If no target exists, search Current entries for an equivalent lesson.
   Compare action, conditions and evidence; reuse a complete equivalent.
   Report conflicting claims without overwriting either.
5. Otherwise create the target from the whole brief, with Status: Current
   and Source brief: <brief-path>. Preserve every qualification.
6. Read the destination back. Only if complete, set the brief to
   Status: Imported and add Entry: <destination-path>. Retain the brief.

Return created, reused, unresolved and unchanged paths.
Never invent verification or claim transactional/concurrent guarantees.

.claude/agents/journal-curator.md

---
name: journal-curator
description: Propose a scoped Draft guideline from selected Current journal entries.
tools: Read, Grep, Glob
---

Read CLAUDE.md, the selected Current entries and relevant existing guidelines.
Do not write files, approve rules or change entry statuses.

Check evidence, applicability, exceptions, conflicts and stale facts.
Repetition is not independent proof. Unverified claims remain Open points
and never become Rules. Label guidance based only on observations Observed.
If support is insufficient, report the gap instead of inventing a rule.

Return a proposed filename in journal/guidelines and the complete guideline
format specified in CLAUDE.md. State whether it adds to, refines or conflicts
with existing guidance; preserve contrary evidence and unresolved questions.
The owner saves the Draft and decides approval. Never mark it Approved.

The path instructions guide the keeper; they do not create a sandbox. Session permissions still apply. The tool list restricts the role's capabilities, while the import's correctness must be checked in the resulting files.

Follow a note through to the next session

Create journal/inbox/demo-obsidian-storage.md. This sample record comes from the documentation: it contains a checked fact and, separately, a benefit that still needs verification.

# demo-obsidian-storage
Status: Pending
Domain: Journal storage
Summary: Obsidian stores Markdown notes in a local vault folder.
Applies when: Choosing a text-note archive accessible through file tools.
Confidence: Verified

## Evidence
Obsidian Help, "How Obsidian stores data", opening and Vault settings.
https://help.obsidian.md/Files+and+folders/How+Obsidian+stores+data
Checked: 2026-11-02. Notes are plain Markdown; .obsidian holds vault settings.

## What to do
Point authorized agent file tools at the chosen notes folder.
Keep vault settings separate from journal content.

## Open points
Unverified: this arrangement reduces mistakes in later agent sessions.

Start claude from the journal-demo/ root. Run /context and check that CLAUDE.md appears among the loaded files. If a session was already open before you created the first .claude/agents/ directory, restart it.

In the chat, type @ and select journal-keeper from the agent list. An explicit mention selects the role to run; simply naming it in a sentence leaves the choice to Claude. You can also send:

@agent-journal-keeper Import only journal/inbox/demo-obsidian-storage.md.
Read CLAUDE.md first. Preserve the evidence and the Unverified open point.
Report the resulting paths when the import is complete.

Wait until the journal-keeper task is marked complete and read its result before checking the files. Open the files in your editor: journal/entries/demo-obsidian-storage.md should exist with Status Current, all the evidence, the Unverified open point and Source brief. The original should remain in the inbox with Status Imported and an Entry path. If the destination is missing or incomplete, the import has failed: keep the brief Pending, compare the files and resolve the discrepancy before retrying.

Repeat the same request. There should still be just one entry for that brief. Then close the session and start a new one from the same root:

Without changing files, consult the journal and explain how Obsidian stores
the notes, which folder contains the vault-specific settings, and what evidence
supports the answer. Distinguish the verified fact from the open point.

Check that the agent retrieves the note, gives its path and preserves its conditions. It must keep the unverified claim about fewer mistakes separate.

To try the curator:

@agent-journal-curator Read CLAUDE.md and
journal/entries/demo-obsidian-storage.md. Propose guidance for storing
journal text notes in a folder accessible through file tools.
Return the complete Draft and its proposed filename. Keep the
Unverified benefit out of the Rules. Do not modify files.

The curator should return a proposal with scope, rules, exceptions, sources and open points, or explain why the evidence is insufficient. Review the proposal. If you keep it, use your editor to create the suggested file under journal/guidelines/ with Status Draft. It becomes Approved only after an explicit decision by the owner. Check that evidence about Markdown notes has not become a promise to reduce errors.

To check a simple failure case, copy the brief with a new ID matching its filename, Status Pending and no Evidence section. The keeper should leave it Pending and report the missing section. If it imports the brief anyway, the configuration needs a correction: the instructions did not produce the required behaviour.

These checks concern the results of individual requests. The configuration files follow the documentation; they are not a deterministic importer or evidence of reliability when several sessions write at once.

Open the same files in Obsidian

Obsidian is optional. After installing it, choose Open folder as vault → Open in the vault manager and select journal-demo/journal/, following the official procedure. Open the imported note; a change saved from your editor should appear in Obsidian too.

The application creates .obsidian/ for the vault’s settings. CLAUDE.md and .claude/agents/ remain outside the vault, at the trial folder's root. For links that work elsewhere too, use standard Markdown syntax. You can turn off Use [[Wikilinks]] in Settings → Files and links, as described in the linking guide.

The local trial needs neither Sync nor community plugins. Keep only one keeper active and do not edit its files at the same time. Sync does not provide real-time collaborative editing of the same file.

Adapt the configuration to your environment

The paths in this trial are relative to journal-demo/. To share the journal across projects, choose one location, update the paths consistently in the instructions and roles, and authorise access in each environment. Repeat the trial from every project that will use it.

With Notion, the keeper needs a service connection and the actual collection identifiers, fields and statuses. Searches and property reads replace Grep and Read on files; writes use authorised Notion tools. The role's tool list needs adapting too: copying the local keeper does not give it access to Notion. The final check is still the saved record, with the right provenance and status.

Keeping the cost visible

Using Notion creates a dependency on the service and access to it. A short file may be enough for a few notes maintained by one person; a procedure tied to a code revision is closer to its context in the repository.

The main cost to assess is maintaining the information: correcting stale notes, reconciling duplicates and checking that a summary has not turned a particular case into a general instruction. In his presentation on context engineering at LinkedIn, Ajay Prakash describes modular playbooks and addresses maintenance, stale information and human review. A saved procedure still needs someone responsible for it.

The entries examined here document the process and individual cases; they do not measure a reduction in errors or working time attributable to the journal. To test its usefulness, I would propose a comparison on the same task, with the same model, environment and budget: the journal on one side, and a short, maintained playbook with the same information on the other. Both should contain a relevant note, a superseded one and a similar one that does not apply.

I would examine separately which source is retrieved, which version is selected, whether the action is correct and what consultation costs. I would also include the time needed to create and maintain both archives. If the journal caused the agent to miss the right note or apply a superseded one, that case would challenge the expected benefit. This test has yet to be run.

For now, I would judge a new entry by a concrete question: which decision could it help justify in the next task, and which conditions must it preserve for that decision to remain sound?