sources/wiki split, truth-timeline page structure, and MCP server

[kelsi-bizer]

Summary

Three concrete patterns borrowed from the GBrain and Karpathy-pattern comparisons we discussed, all within BizerOS Knowledge's filesystem-pure philosophy:

1. sources/ vs pages/ vs daily/ folder split (Karpathy-inspired)
2. Compiled-truth + timeline page structure (GBrain-inspired)
3. MCP server so the brain works with any MCP-capable agent, not only those that load .agents/skills/

Nothing in here adds a database, an embedding pipeline, or any external dependency. The brain is still a folder of plain .md files; the new patterns just make the convention sharper and the agent surface broader.

1. Folder convention update — .agents/skills/bizeros-knowledge/SKILL.md

The skill now teaches three distinct folders with three distinct jobs:

Folder	Role	Mutability
sources/	Raw, immutable inputs — transcripts, articles, email dumps, dictated notes	Agent: read + append-only (never rewrite the body)
pages/	The wiki: synthesized topical or per-entity notes	Agent: owns — creates, maintains, restructures
daily/	The user's journal, one note per day	User's home turf — agent appends conservatively

The boundary that matters most: sources/ is the receipts, pages/ is the synthesis, daily/ is the human's voice. The agent's procedures are now split accordingly — "Capturing from a conversation" updates daily/; a new "Ingesting a source" procedure files raw input under sources/ and links it back to the relevant pages/.

2. Page structure — compiled truth + timeline

Every pages/<Entity>.md now follows:

# Sarah Johnson

Lead engineer on Project Aurora. Joined March 2025. Lives in Berlin.
Reports to Marcus. Owns the API redesign.

---

## Timeline

- 2026-05-09 — Mentioned in [[daily/2026-05-09]]: "Sarah will own the launch checklist by Friday"
- 2026-04-22 — Source [[sources/q2-review-transcript]]: confirmed as Aurora lead
- 2026-03-14 — First mentioned in [[daily/2026-03-14]]: introduction

The compiled truth above the --- is rewritable — the agent keeps it current as facts evolve. The timeline below is append-only — every meaningful piece of evidence gets a new dated entry with a back-link to where it came from. Never edited, never deleted.

This solves a real problem with pure-markdown knowledge bases: provenance. When the agent says "Sarah lives in Berlin," the user can scroll down and see which raw note that came from and when. Without this convention, the agent either hallucinates or gets stuck in conservative "I'm not sure" mode.

New pitfalls in the skill: never rewrite sources/, never delete or edit timeline entries.

3. MCP server — packages/mcp-server

New package exposing the same four tools (list_notes, search_notes, read_note, write_note) over the Model Context Protocol via stdio.

Why this matters: agentskills.io skills work great in Hermes, OpenClaw, and Claude Code, but MCP is the broader, more portable standard. Adding an MCP server makes BizerOS Knowledge usable from any MCP-capable agent — Claude Code, Cursor, MCP-Inspector, custom clients — by adding one line to their MCP config:

{
  "mcpServers": {
    "bizeros-knowledge": {
      "command": "node",
      "args": ["/opt/bizeros-knowledge/packages/mcp-server/src/server.js"],
      "env": { "BRAIN_DIR": "/srv/bizeros/brain" }
    }
  }
}

Implementation

packages/mcp-server/
├── package.json                # @modelcontextprotocol/sdk ^1.27.1
├── src/
│   ├── brain.js                # filesystem ops (mirrors brain_tools.py)
│   └── server.js               # MCP Server + StdioServerTransport
└── test/
    ├── brain.test.js           # 12 tests on the filesystem layer
    └── server.test.js          # 6 tests at the MCP protocol layer

src/brain.js mirrors the same safety contract as brain_tools.py: path traversal blocked via path.relative() check, null bytes rejected, atomic writes (tmp + rename), consistent {ok, ...} return shape.

Tool descriptions in server.js carry the new conventions through to the agent — the write_note description explicitly mentions the compiled-truth + timeline structure so MCP-only agents (which don't load the SKILL.md) get the same guidance.

Tests

18 passing (node --test test/*.test.js):

• brain layer (12): round-trip, .md auto-append, traversal blocked, null byte rejected, search returns first matching line as snippet, list sorted alphabetically.
• protocol layer (6): tools/list exposes all four tools with full schemas; tools/call round-trips read+write; unknown tool names handled; traversal rejected at the protocol boundary too.

End-to-end MCP stdio smoke test (passed)

Drove the server with a real JSON-RPC sequence:

• initialize → server announces capabilities
• tools/list → all 4 tools with descriptions and JSON Schema
• tools/call write_note → {"ok":true,"path":"pages/Hello.md","bytes":19}
• cat /tmp/brain-mcp-live/pages/Hello.md → exact content

What's not touched

• packages/notes-app — web UI unchanged.
• packages/file-api — HTTP file service unchanged.
• Docker image — unaffected; nothing in the build context changed.

Test plan

• cd packages/mcp-server && pnpm install && pnpm test — 18 tests pass
• Configure Claude Code (or any MCP client) with the snippet above, then ask the agent to "list my notes" — it should call list_notes via the MCP server and return the contents of $BRAIN_DIR
• Have the agent capture a meeting → it should write daily/<today>.md with [[wiki links]] and create/update relevant pages/<Entity>.md files following the truth + timeline pattern
• Drop a transcript into sources/2026-05-XX <topic>.md → agent extracts entities, links from pages/<Entity>.md timelines back to [[sources/2026-05-XX <topic>]]

---

Generated by Claude Code