Proposed Structure Refactor

[HarKro753]

feedback.pdf

Id Propose changing the underlying Obsidian Strcuture to a Folders as Infrastructure Approach with Categorie Properties being the domain separation. I have attached a propsal paper. Since this is a pretty big refactor i guess.

This btw is the approach which also the CEO of obsidian uses. Which i myself also use in my personal obsidian book.

It generally just reduces the number of questions which the agent has to ask regarding in which folder to put something. SO insertion generally only involves thiinking about tags,categories and the one folder to put it in. Retriving information mostly involves using obsidians native tools such as tag search, categorie search instead of searching in the file tree.

It involves injecting tags and categories before working. This trade off has not been formally analyzed by me but i roughly calculated a reduction in error nodes and general token consumption

[breferrari]

Hi @HarKro753, thanks for the proposal. I read the PDF in full and audited v6.0 / main to ground my response. There's a lot worth engaging with, and also some specific places where the argument needs adjustment before this becomes actionable.

Process request first. Please paste the proposal contents into the issue body. Right now anyone landing on this issue has to download a PDF to see what's being argued, and reviewers can't quote or respond inline. The proposal is too substantive to leave buried in an attachment.

On the structural argument: this is the strongest part. You're right that the current folder set doubles as a type system, and that capture-time multi-axis classification (what is this note, which folder, which indexes) is real friction even with the hook hints. Moving primary identity into a category: field with cross-cutting tags is a cleaner type system. The downstream wins I see:

• Single primary identity makes duplicate filing visible. A note has exactly one category, so the temptation to file the same insight as Pattern, Gotcha, and project note disappears.
• Wrap-up validation becomes uniform ("for each category touched, run the consolidation step") instead of folder-keyed.
• The PostToolUse validator can assert "category in enum, tags in registry" as a structural invariant more cheaply than "this note is in the right one of 13 destinations."

These are real wins and worth pursuing on their own merits. Worth flagging though: CLAUDE.md on main already says "Folders group by purpose, links group by meaning" and "Folders are for browsing convenience, not for categorization. Before creating a new subfolder, ask: 'Can I solve this with a tag, a property, or a link instead?'" So the philosophical direction is already in the repo. Your argument is really that the implementation is incomplete: some current folders (work/incidents, brain/Patterns.md, etc.) still encode workflow semantics rather than just storage. That's defensible and I think we agree on it.

On the 35-55% token claim: this is where I get stuck. I rebuilt the memory-management token budget bottom-up against the actual injection surface in v6.0:

Layer	Range	Midpoint
SessionStart (file listing, North Star, active work, recent git, tasks, operating contract)	1,200-3,000	2,100
UserPromptSubmit × ~30 messages	1,500-6,000	3,750
PostToolUse × ~5 writes	0-1,500	400
Stop checklist	200-500	350
QMD retrieval × ~3 rounds	3,000-15,000	9,000
Total	~5,900-26,000	~15,600

The paper's 9,750 baseline skews low because it appears to under-count QMD retrieval rounds, which dominate the budget. The load-bearing issue: the refactor doesn't change QMD. If ~60% of the budget is unchanged, a 35-55% total reduction requires the remaining 40% to essentially vanish, which isn't plausible.

A few specific places where the math doesn't track for me:

1. The argument "fewer routing branches yield fewer tokens" conflates decision complexity with inference cost. The cost of describing 8 routing options in CLAUDE.md is the ~200-400 tokens to render the list once, not per-call. Collapsing to a category enum saves ~200 tokens once, not multiplicatively.

2. The refactor's SessionStart isn't obviously smaller. Under the new model you still need a category registry (~13 categories with definitions), tag registry or canonical-vocabulary guidance (otherwise tag-scoped retrieval drifts), Base entry-point descriptions, and residual folder rules. The current injection's file listing, active work, and recent git are unchanged. Net effect is plausibly neutral or slightly larger, not 50% smaller.

3. Frontmatter rides along with retrieved notes. Mandatory category: plus 2-6 tags is ~50-150 tokens of YAML per retrieved note. At ~3 retrieval rounds × 2-3 multi_get notes, that's +300-1,350 tokens per session of pure overhead. Not catastrophic but cuts against the savings story.

My honest estimate is the refactor's net token impact lands somewhere between -15% and +10% on memory-management overhead, dominated by the operating-contract size and retrieval frontmatter. There may be a small precision win on retrieval (tighter candidate sets reducing follow-up rounds) but that's measurable, not assumable.

On Obsidian Bases: I think this is mischaracterized in the paper. Bases is a frontmatter-property-filtered view feature for humans, defined by .base YAML files. kepano's own obsidian-skills repo teaches agents to author .base files for human consumption, not to query them as a runtime API. When a Claude Code agent operationally "uses Bases" it's either writing the YAML or doing frontmatter grep, which it would do without Bases. Table I describing Bases as "Category/tag retrieval entry points" is conflating a UI affordance with a runtime mechanism. The retrieval path under the refactor is the same as today: filter by frontmatter, then QMD ranks.

On the Steph Ango reference: small note. His published writing on minimal folders is about human ergonomics (speed, decision fatigue, durability), not LLM efficiency. He explicitly says he doesn't want to delegate his vault to language models. Citing him is fine as evidence that the structure works for personal note-taking, but it doesn't carry over to "this is therefore better for coding agents." That's a separate claim that needs its own evidence.

What would move this forward. If you want this evaluated as an engineering proposal rather than a design philosophy post, the four most useful artifacts:

1. A concrete sample SessionStart payload for the refactored vault, side-by-side with the current one, with token counts measured against Claude's tokenizer. This single artifact would settle most of the disagreement about operating-contract size.
2. A prototype branch applying the refactored ontology to ~50 representative notes, plus a script that runs three scripted sessions (capture-heavy, retrieval-heavy, wrap-up-heavy) on both versions and reports input_tokens / cache_read_input_tokens / output_tokens from the API response objects.
3. A retrieval precision/recall comparison on ~20 test queries: same QMD index, same queries, different ontologies. This is the strongest non-token claim and it's directly measurable.
4. An accounting of frontmatter overhead per retrieved note under the proposed schema, and the retrieval-count reduction needed to break even.

If those bear out the headline number, I'm happy to be wrong and move forward. If they show single-digit savings, the proposal is still worth pursuing on the structural, validation, and ergonomics grounds, just with the framing adjusted to lead with those.

Happy to keep the discussion going. Leaving open.

[HarKro753]

Thanks for the feedback. I will work on it 👍🏻