A second brain for Claude Code.
Every plan, decision, and lesson lives in plain markdown with YAML frontmatter, in your repo. Readable by you, greppable by anything, and retrieved with precision by your agents, because HeySpex wrote the files it is searching.
Files you can read. Structure agents can trust.
The vault is typed entities as markdown: tasks, epics, milestones, research, decisions, lessons. Each file carries YAML frontmatter with a stable ID, a status, and its dependencies. Every field is visible in any editor. Nothing hides in a proprietary database, and `git log` is the audit trail.
That means the second brain survives everything: a dead laptop, a switched agent, an abandoned subscription. Clone the repo and it is all still there.
--- id: HS-STRP-TASK type: task status: open depends_on: [HS-ONBS-TASK] effort: one_session ---
Wire the Stripe setup result into [[HS-ONBS-TASK]]'s state machine. Retry handling is out of scope, see[[HS-WBHK-TASK]].
Most second brains become graveyards. This one is load-bearing.
The failure modes are well documented: capture feels productive so the archive grows and is never read, upkeep depends on discipline so the system dies the week you get busy, and a vault that was pleasant at 300 notes punishes every shortcut at 3,000. HeySpex was designed against each one.
Precise retrieval. No embeddings.
HeySpex owns both sides of the workflow: the conventions the docs are written with, and the queries that fetch them back. When author and retriever share typed frontmatter, stable IDs, and wikilinks, plain lexical retrieval is enough, and it is fast, exact, and explainable. No vector database, no embeddings drift, no similarity guesswork.
The MCP server hands your agent the right spec in milliseconds, and the same query always returns the same answer. That is the same promise the rest of HeySpex makes: nothing here is a model's opinion, so the second brain is safe to wire into agents that are not deterministic.
● heyspex_recall("stripe webhook retries") 1 exact hit · 12 ms · lexical, no embeddings specs/memory/lessons/HS-WBHK-LES-stripe-idempotency.md:7 "Stripe webhooks need idempotency keys. Retries double-charged in staging." links: [[HS-WBHK-TASK]] · [[HS-STRP-TASK]] ● loaded into context pack · 412 tokens
Links that never lie.
Specs get superseded. That is healthy. What is not healthy is a vault full of links that quietly point at dead decisions.
In HeySpex, wikilinks are self-healing. When a spec is superseded, its frontmatter records the canonical successor, and references to it are marked superseded where they stand, inline. Follow an old link and it tells you where the truth moved instead of letting you build on a retired plan.
--- id: HS-AUTH-SPEC status: superseded superseded_by: HS-AUTH2-SPEC ---
Obsidian-compatible. Not a notes app.
Point Obsidian at the vault and it just works: wikilinks, backlinks, the graph, all of it. The difference is everything that happens around the files. Obsidian stores what you type. HeySpex runs the workflows that create the docs and the workflows that retrieve them, so the vault stays a settled operating record instead of a pile of notes.
Read the full comparison →The other half is dispatch.
A second brain is only useful if agents act on it at the right moment. That part is covered in Agent workflows.