Building a Trading Journal Your AI Agent Can Read

hero illustration

A trading journal becomes much more useful when your AI agent can read it, update it, and understand what each file means.

The trick is not a fancy database. It is a plain-text vault with predictable folders, clean YAML frontmatter, and one note per trade, strategy, and review.

For most crypto investors, Obsidian is a good fit because it stores notes as local markdown files. That means you can read them like normal notes, while an agent can parse them like structured memory. Tools like the official obsidianmd/obsidian-mcp server, Smart Connections by @brianpetro_, and Obsidian Copilot by @logancyang are already pushing this pattern forward.

Quick takeaway: Build your trading journal as markdown files with consistent folders and YAML fields, so your agent can search trades, follow strategy links, update exits, and audit your decisions without guessing.

Why plain markdown works so well

A trading journal has two jobs.

  • Help you remember what you were thinking when you entered a trade.
  • Help you review whether that thinking was good later.

An AI agent adds a third job: the journal needs to be readable by software.

That is where markdown is useful. A markdown file is just plain text. You can open it in Obsidian, Cursor, VS Code, or any basic text editor. An agent can read the same file without needing a special export.

Per the research material, the current agent-memory stack usually has three layers:

  • Obsidian as the vault: local markdown files on your machine.
  • MCP as the bridge: the official obsidianmd/obsidian-mcp server exposes tools like read_note, write_note, search_vault, and list_notes to MCP-compatible agents.
  • Semantic search as the memory layer: Smart Connections and Obsidian Copilot can help find related notes by meaning, not just exact keywords.

There is also a mature community MCP option, nickbaumann98/obsidian-mcp-server, which adds batch operations and more granular file control.

The important point is simple: your agent should not have to “remember” your trading history inside one chat. It should read your journal from disk every time.

The folder structure I would start with

Folders are not just for keeping things tidy. For an agent, folders act like a schema.

If a file is inside positions/, the agent knows it is probably a trade. If it is inside strategies/, it knows to look for rules. If it is inside post-mortems/, it knows that file is about review, not execution.

Here is a practical starter vault:

trading-vault/
  _templates/
    trade-log.md
    weekly-review.md
    strategy-card.md
  00-META/
    manifest.md
    schemas.md
  positions/
    btc-long-2025-05-21.md
    eth-perp-2025-05-20.md
    sol-short-2025-05-19.md
  strategies/
    momentum-breakout.md
    mean-reversion.md
    eth-liquidation-sweep.md
  watchlists/
    defi-tokens.md
    layer-2-play.md
  research/
    ethereum-pectra-upgrade.md
    ai-agent-tokens-landscape.md
  post-mortems/
    2025-q1-review.md
    2025-04-review.md
  macros/
    fed-fomc-may-2025.md
  journal/
    2025-05.md
  dashboards/
    pnl-overview.md
    win-rate-by-strategy.md

You can use numbered folders if you want Obsidian to sort them in a specific order. The research file suggests a larger version with 00-META/, 01-Research/, 03-Trades/, 04-Strategies/, and 08-Agents/. That works well if your vault is growing into a broader crypto operating system.

For a beginner, I would not overbuild it. Start with five folders:

  • positions/ for one note per trade.
  • strategies/ for the rules you claim to follow.
  • research/ for token notes, protocol notes, and clipped sources.
  • post-mortems/ for weekly, monthly, or quarterly reviews.
  • 00-META/ for instructions your agent reads before touching anything.

Add a manifest so the agent does not guess

The first file your agent should read is 00-META/manifest.md.

This is the note that explains what the vault is, where files live, and what the agent is allowed to do. Without this, the agent has to infer your system from scattered files. That is where mistakes happen.

---
agent_role: "Trading Journal Keeper"
capabilities:
  - read_trades
  - create_trade
  - update_trade_status
  - analyze_performance
  - suggest_improvements
vault_structure:
  positions: "Individual trade records, one file per trade"
  strategies: "Strategy definitions and rules"
  watchlists: "Assets under observation"
  research: "Fundamental and thesis research"
  post-mortems: "Periodic performance reviews"
frontmatter_schema: "00-META/schemas.md"
---

This file is boring. That is the point.

You are telling the agent: “Here is the map. Use it.”

Use YAML frontmatter for every trade

YAML frontmatter is the block of structured fields at the top of a markdown note. Obsidian supports it. Agents can parse it. Humans can still read it.

Here is a trade note based on the research material:

---
type: trade
id: btc-long-2025-05-21-001
asset: BTC/USDT
asset_type: spot
side: long
status: closed
exchange: Binance
date_entered: 2025-05-21T09:30:00Z
date_exited: 2025-05-21T14:15:00Z
timeframe: 1h
strategy: momentum-breakout
entry_price: 67450
exit_price: 68900
stop_loss: 66800
take_profit: 69200
position_size: 0.5
position_unit: btc
risk_pct: 1.2
risk_reward_ratio: 2.1
pnl_usd: 725.00
pnl_pct: 2.15
fees: 3.50
tags: [breakout, momentum, btc, scalping]
rationale: "Broke above 67k resistance with volume. Tight stop under 66.8k."
lessons: "Exit too early — missed additional 3% move. Let runners breathe."
rating: 7
---

The field names matter more than the exact values.

  • type tells the agent this is a trade, not a strategy or research note.
  • id gives the note a stable reference for deduping and linking.
  • status lets the agent filter draft, open, closed, and cancelled trades.
  • strategy points back to the strategy note.
  • pnl_usd, pnl_pct, fees, and risk_pct are raw numbers, not decorated text.

Do not write $725 or 2.15% inside numeric fields. Use 725.00 and 2.15. The dollar sign and percent sign are nice for humans, but they make calculations messier for the agent.

Make strategy notes just as structured

A trade journal is weaker if your strategy rules live only in your head.

If you enter a “momentum breakout” trade, the agent should be able to open strategies/momentum-breakout.md and check what that strategy means.

---
type: strategy
id: momentum-breakout
status: active
asset_class: crypto
timeframes: [15m, 1h, 4h]
indicators: [EMA20, EMA50, RSI, Volume]
entry_conditions:
  - "Price closes above 20EMA on 1h"
  - "RSI > 55 and < 75"
  - "Volume > 1.5x 24h average"
exit_conditions:
  - "Price closes below 20EMA"
  - "Trailing stop at 2x ATR"
risk_per_trade_pct: 1.0
max_drawdown_pct: 15
win_rate_target: 55
tags: [momentum, trend-following]
---

This turns a vague label into an auditable rule set.

Later, you can ask:

  • “Which BTC trades broke my momentum-breakout rules?”
  • “What is my win rate for trades tagged momentum?”
  • “Did I lose money because the strategy failed, or because I ignored the exits?”

The agent can only answer those questions if the data exists in a consistent place.

How the agent reads your journal

A good agent workflow should be predictable.

When a session starts, the agent should not scan the whole vault blindly. It should follow a read path:

  1. Read 00-META/manifest.md for vault instructions.
  2. Read 00-META/schemas.md for field definitions.
  3. Search positions/ for type: trade and status: open.
  4. Read each open trade note for entry, stop, target, and rationale.
  5. Follow the strategy field to the matching file in strategies/.
  6. Answer the user using only what it found, unless asked to reason beyond it.

So if you ask, “What is my ETH position?” the agent should search for notes where asset: ETH/USDT or the filename contains eth. It should not invent a position from memory.

This is also where semantic search helps. Smart Connections, which the research file notes has 250k+ downloads, creates embeddings for notes so you can ask broader questions like “find notes about momentum strategies.” Obsidian Copilot can add a chat interface and custom personas, including a “Trading Analyst” persona that focuses on your Strategies/ and Trades/ folders.

If you care about privacy, use local models through Ollama or LM Studio where supported. Crypto notes can reveal more than people think.

How the agent writes back

Writing is where you need rules.

An agent that reads your journal is low risk. An agent that edits your journal can create confusion if it overwrites the wrong file or changes history without a trace.

A safer write flow looks like this:

  1. You say: “Log my BTC long at 67450, stop 66800, target 69200.”
  2. The agent creates a new note from _templates/trade-log.md.
  3. It writes the note to positions/btc-long-2025-05-21.md.
  4. It sets status: open.
  5. It leaves blank fields like date_exited, exit_price, and pnl_usd until the trade closes.

When you later say, “BTC hit target, close the trade,” the agent should:

  • Read the existing trade note first.
  • Update status: closed.
  • Add date_exited, exit_price, pnl_usd, pnl_pct, and fees if known.
  • Append a short lesson instead of deleting your original rationale.

That last part matters. Your original reasoning is the evidence. Do not let an agent “clean it up” after the outcome is known.

Use Git so your memory has a history

Git is not just for software developers. It is version control for your trading memory.

If your vault is a Git repo, every edit can be tracked. You can see when a strategy changed, when a trade was closed, and how your thinking evolved from one month to the next.

A simple .gitignore from the research material:

.obsidian/workspace
.obsidian/cache
.obsidian/plugins/obsidian-git/data.json
*.excalidraw
.trash/

And a simple .gitattributes:

*.md diff=markdown

For commits, use short labels:

  • [trade] BTC long closed +725
  • [strategy] updated momentum entry conditions
  • [research] added pectra upgrade notes
  • [review] May post-mortem completed

The Obsidian Git plugin can auto-commit on a timer. Monthly tags like v2025-05 and v2025-06 can create snapshots your agent can reference later.

One warning: use a private repo only. Turn on 2FA. If you want tighter control, use self-hosted Gitea instead of a public cloud Git host.

Privacy rules for crypto journals

A trading journal can leak more than you expect.

Do not store seed phrases. Do not store private keys. Do not store exchange API keys. I would also avoid saving full wallet addresses unless there is a strong reason.

Good privacy defaults:

  • Keep the vault local on disk unless you deliberately choose sync.
  • Use a private Git repo with 2FA if you back it up remotely.
  • Consider two vaults: one private journal that never syncs, and one research vault that can sync.
  • Use percentages instead of raw PnL when you do not need exact dollar amounts.
  • Use local Ollama or LM Studio models if you do not want vault contents sent to third-party APIs.

The official Obsidian Web Clipper, from obsidianmd/obsidian-clipper, can save articles, dashboards, governance proposals, and X threads into your vault. That is useful. Just remember that clipped research and personal trade logs do not need the same privacy settings.

Tools worth knowing

Here are the specific tools and projects from the research material that fit this setup:

  • Obsidian: the local markdown vault.
  • obsidianmd/obsidian-mcp: official Obsidian MCP server with tools like read_note, write_note, search_vault, and list_notes.
  • nickbaumann98/obsidian-mcp-server: community MCP server with batch operations and more granular file control.
  • Smart Connections by @brianpetro_: semantic search and chat against your vault, with local LLM support through Ollama and LM Studio.
  • Obsidian Copilot by @logancyang: chat interface with custom personas, supporting OpenAI, Anthropic, Ollama, and Azure.
  • obsidianmd/obsidian-clipper: official browser extension for clipping web research into Obsidian.
  • Model Context Protocol: the open standard at modelcontextprotocol.io that lets agents connect to tools and data sources.

The research also notes builders like @mckaywrigley, @transitive_bs, @mattprd, @thesephist, @yoheinakajima, and @chrishayuk discussing local markdown and Obsidian-style vaults as agent memory. X API access was unavailable during research, so treat that as directional signal, not a live citation.

Protect the accounts around your journal

Your trading journal should never contain seed phrases or private keys. Still, it may contain enough information to make you a target: exchanges used, position sizes, PnL, wallet habits, and strategy notes.

Shop Ledger hardware wallets
Try NordVPN

Disclosure: These are affiliate links. Easy as Pie DeFi may earn a commission if you buy through them, at no extra cost to you. We only include tools that fit the security habits we already recommend.

Bottom line

A good AI-readable trading journal is not complicated: use plain markdown, stable folders, strict YAML fields, strategy links, and Git history. The payoff is simple — your agent can stop guessing and start working from the same record you use.