Open #2 Enhancement

filed by gabriel human · 33 days ago · assigned to aaronrene

feat: Knowtation domain — vault-native VCS intelligence for agent knowledge systems

0 Anchors

— Blast radius

— Churn 30d

0 Proposals

Summary

Knowtation is a vault-centric agent knowledge system: 17 import types, 33-tool MCP server, 5 memory provider tiers, LLM consolidation, ICP attestation, and a full Hub — all grounded in Markdown files the user owns. It is also the ideal candidate for Muse's first knowledge domain: a plugin layer that makes Muse version-control-aware of note identity, memory events, frontmatter semantics, and cross-note reference graphs.

This ticket is a load-bearing implementation plan in phase order. Each phase unlocks the next. No phase should begin before its predecessor is merged.

Why this matters

Code domains gave Muse symbol-level intelligence over source files. A Knowtation domain does the same for knowledge: every note becomes a first-class versioned object with semantic identity, diff-aware merge, vector history, and agent-readable provenance. The combination is a new primitive — a knowledge base that is also a commit graph — with properties neither Knowtation nor Muse can achieve alone.

For Muse: expands the domain model beyond code and MIDI to agent memory, proving the domain interface generalises to any structured text artifact.
For Knowtation: every write is signed, content-addressed, conflict-resolved by policy, and auditable forever — far stronger provenance than a bare git repo.
For users: a vault you can clone, branch, merge, bisect, and query with the same intelligence layer as code.

Phase 1 — Domain Foundation

Goal: Muse recognises Knowtation vault files as a distinct domain and can introspect them structurally.

1.1 File type registration

Register the knowtation domain in muse/domains/. A vault file is any .md file whose frontmatter contains at least one of: source_type, source_id, project, tags, or entity. Files without Knowtation frontmatter fall through to the mist (prose) domain.

muse/domains/knowtation/
  __init__.py
  detector.py        ← detects vault files from frontmatter fingerprint
  parser.py          ← extracts symbols: title, sections, frontmatter keys, entity refs
  differ.py          ← section-aware diff (Phase 2)
  merger.py          ← harmony-aware merge (Phase 2)
  plugin.py          ← DomainPlugin subclass wiring it all together

Detection heuristic (in priority order):

Frontmatter key source_type present → knowtation
Frontmatter key source_id present → knowtation
Frontmatter project or tags array alongside a date field → knowtation
Fallback: mist

1.2 Symbol model for vault notes

A vault note exposes the following symbol addresses:

Address	Kind	Description
`notes/my-note.md`	`note`	The whole note as a unit
`notes/my-note.md::title`	`field`	The H1 or frontmatter `title`
`notes/my-note.md::source_type`	`field`	Import origin (url, pdf, chatgpt, …)
`notes/my-note.md::source_id`	`field`	Stable import dedup key
`notes/my-note.md::project`	`field`	Project scope
`notes/my-note.md::tags`	`field`	Tag array
`notes/my-note.md::entity`	`field`	Named entity references
`notes/my-note.md::§Intro`	`section`	Heading-level body section
`notes/my-note.md::§Summary`	`section`	…

This gives muse code grep, muse code cat, muse code impact, and muse code symbols full coverage of the note graph.

1.3 `.museattributes` defaults for vault repos

Ship a recommended .museattributes snippet in the domain docs:

*.md   domain=knowtation   merge=knowtation-3way
*.md   harmony-tier=2
vault/inbox/**   merge=prefer-newer-date

1.4 `muse domain-info` output

muse domain-info --json for a knowtation repo should return:

{
  "domain": "knowtation",
  "note_count": 847,
  "source_types": ["url", "pdf", "chatgpt", "markdown"],
  "projects": ["research", "inbox", "clients"],
  "entity_count": 312,
  "tag_count": 94,
  "index_freshness": "2026-05-04T11:22:00Z"
}

Deliverables: detector.py, parser.py, plugin.py wired, muse domain-info output correct, muse code symbols --file note.md returns note + section + field symbols.

Phase 2 — Semantic Diff & Harmony Merge

Goal: Muse understands what changed inside a note — not just which bytes — and resolves conflicts by policy rather than panic.

2.1 Section-aware diff

The knowtation differ splits a note into layers before diffing:

Frontmatter layer: key-value map diff (structural, not line-level)
Title layer: H1 change
Section layer: each ## Heading block is diffed independently
Body layer: prose diff within sections (character-level, rendered as +/- lines)

muse diff output for vault files shows which section changed, not a raw hunk dump. Example:

§Summary  modified  (+3 lines, -1 line)
tags      modified  ["research"] → ["research", "agents"]
source_id unchanged

2.2 Harmony policies for common vault conflicts

Vault repos are written by multiple agents and humans simultaneously. Pre-ship policies that handle the predictable cases:

Conflict pattern	Policy	Rationale
Same `source_id`, different body	Prefer note with newer `date` frontmatter	Import dedup: same source, freshest wins
Conflicting `tags` arrays	Union merge (sorted)	Tags are additive; no information is lost
Conflicting `project`	Prefer theirs if both are non-empty; else prefer-ours	Branch-level ownership
Conflicting `entity` arrays	Union merge	Same as tags
Conflicting section `§Summary`	Escalate to Tier 4 (create hub issue)	Summaries are high-value, need human review
Binary note conflict (both agents rewrote body)	Semantic fingerprint → try Tier 3 replay; else escalate	LLM-mediated resolution

2.3 Three-way merge for note content

The knowtation merger implements MergeStrategy.three_way:

Frontmatter: field-level three-way (not line-level)
Body: section-level three-way — if only one side touched §Intro, take it; if both touched it, diff the diffs and apply non-overlapping hunks; overlapping hunks go to Harmony Tier 3 or escalate

2.4 `muse code compare` output for vault files

muse code compare HEAD~5 HEAD --json on a vault repo returns:

{
  "notes_added": 12,
  "notes_modified": 34,
  "notes_deleted": 1,
  "frontmatter_changes": [
    {"address": "notes/research/llms.md::tags", "before": ["ai"], "after": ["ai", "agents"]}
  ],
  "section_changes": [...],
  "entity_delta": {"added": ["OpenAI", "Anthropic"], "removed": []}
}

Deliverables: differ.py, merger.py, 6 Harmony policies shipped as defaults, muse merge no longer produces raw-text conflicts on tag/entity fields.

Phase 3 — Code Intelligence over the Knowledge Graph

Goal: Every muse code * command works meaningfully on vault notes, treating the note graph as a dependency and call graph analogue.

3.1 Note graph as dependency graph

muse code deps notes/llms.md --json returns:

Outbound: [[wikilinks]], [text](other-note.md), and entity refs that resolve to other vault files
Inbound: which notes link to this one (reverse index)

muse code impact notes/llms.md --json returns every note that directly or transitively references notes/llms.md — the full blast radius of an edit.

3.2 Note hotspots and gravity

muse code hotspots --json ranks notes by edit frequency. A hotspot note is one agents are writing to repeatedly — a sign it is either load-bearing context or underspecified.

muse code gravity --json ranks notes by downstream reference count. A high-gravity note is one many other notes depend on — treat it like a core module; changes ripple.

3.3 Dead note detection

muse code dead --json surfaces notes that:

Have zero inbound links
Have never been read (no memory query event recorded against them)
Have not been modified in ≥90 days

These are candidates for archival or deletion — same signal as dead code, applied to knowledge.

3.4 Clone detection for notes

muse code clones --json finds notes with identical or near-identical body hashes — duplicated imports from the same source URL, for example. These should be merged or deduplicated.

3.5 Entanglement — notes that always change together

muse code entangle --json surfaces note pairs that are co-modified in the same commits. High entanglement between two notes suggests they should either be merged into one or explicitly cross-linked.

3.6 Velocity per project

muse code velocity --json broken down by project frontmatter value — shows which knowledge areas are actively growing vs. stagnant.

Deliverables: All six muse code commands return meaningful output on vault repos; link/entity indexer runs as part of muse code index rebuild.

Phase 4 — Vault as Agent Memory Timeline

Goal: Map Knowtation's memory event model onto Muse's commit graph so the vault's entire write history is queryable as a structured memory timeline.

4.1 Memory event types as commit metadata

Knowtation defines 15 memory event types (recall, store, consolidate, summarize, verify, discover, …). When an agent commits to the vault using Muse, it embeds the event type in commit metadata:

muse commit -m "memory: consolidate §Summary for project=research" \
  --agent-id knowtation-daemon \
  --model-id claude-sonnet-4-6 \
  --sign \
  --meta '{"event_type": "consolidate", "project": "research", "pass": 2}'

muse log --json surfaces meta.event_type alongside agent_id and model_id.

4.2 `muse code symbol-log` as memory replay

muse code symbol-log "notes/research/llms.md" --json becomes a complete memory timeline for that note: every agent write, consolidation pass, and human edit in chronological order with full provenance.

For agents, this is memory_list with commit-level precision — no separate memory store needed for notes that live in the vault.

4.3 Consolidation as a merge transform

muse merge --consolidate feature/inbox dev runs the Knowtation consolidation daemon as a pre-merge hook:

Identify notes added/modified on feature/inbox relative to dev
Run consolidation pass (merge-by-topic, verify against vault state, discover insights)
Produce a new snapshot where consolidated notes replace the originals
Commit that snapshot as a merge commit with event_type: consolidate

This means the vault's history is always clean: raw memory events live on feature branches; consolidated summaries land on dev and main.

4.4 Session bootstrap from commit history

Knowtation's knowtation://prime resource returns a bootstrap JSON for agents. In a Muse-integrated vault, prime is generated from the commit graph:

{
  "session_id": "...",
  "last_consolidation": "sha256:abc...",
  "active_projects": ["research", "clients"],
  "hot_notes": ["notes/research/llms.md", "notes/clients/acme.md"],
  "suggested_next": ["knowtation://vault/inbox", "knowtation://memory/recent"]
}

hot_notes comes from muse code hotspots; last_consolidation is the most recent commit with event_type: consolidate.

Deliverables: commit metadata schema for event types, muse log surfaces event_type, consolidation pre-merge hook, updated prime bootstrap from commit graph.

Phase 5 — MCP Domain Surface

Goal: All Knowtation domain operations are accessible through Muse's MCP server so any MCP-capable agent (Claude Desktop, Cursor, Copilot) gets vault intelligence without configuring a separate Knowtation MCP server.

5.1 Domain-native MCP tools

Expose as Muse MCP tools (mounted under the knowtation/ namespace):

Tool	Maps to
`knowtation/search`	`muse content-grep` + vector search on vault index
`knowtation/get-note`	`muse cat note.md --json` at a specific commit
`knowtation/history`	`muse code symbol-log note.md --json`
`knowtation/consolidate`	consolidation pre-merge hook on demand
`knowtation/impact`	`muse code impact note.md --json`
`knowtation/dead`	`muse code dead --json` scoped to vault
`knowtation/prime`	session bootstrap from commit graph
`knowtation/propose`	`muse hub proposal create` for note edits
`knowtation/attest`	attach ICP attestation record to a commit

5.2 MCP resources

Resource URI	Content
`knowtation://vault`	Root note listing with frontmatter summary
`knowtation://vault/{path}`	Note content at HEAD
`knowtation://vault/{path}@{ref}`	Note at a specific commit
`knowtation://prime`	Session bootstrap JSON
`knowtation://graph`	Note dependency graph as JSON
`knowtation://memory/recent`	Last 20 memory events (commits with event_type)
`knowtation://projects`	Project list with note counts and last-modified
`knowtation://hotspots`	Top 10 hotspot notes

5.3 Prompts

Prompt	Behaviour
`vault/daily-brief`	Summarise commits from the last 24h across all projects
`vault/search-synthesis`	Run search, surface top 5 notes, generate synthesis
`vault/memory-session`	Load prime, inject recent memory events, resume prior session
`vault/knowledge-gaps`	Cross `muse code dead` with entity index to surface missing coverage

Deliverables: All 9 tools, 8 resources, and 3 prompts registered in the Muse MCP server; integration test with Claude Desktop against a test vault repo.

Phase 6 — MuseHub UI for Vault Repos

Goal: Vault repos on MuseHub render with a knowledge-centric UI — not a code-centric one — surfacing notes, memory stats, and proposals as the primary navigation.

6.1 Domain-aware repo landing page

When domain = knowtation, the repo's Code tab renders:

Note explorer instead of file tree: grouped by project frontmatter
Vault stats bar: note count · unique entities · top tags · last consolidation
Hot notes strip: top 5 hotspot notes with edit frequency sparkbars

6.2 Note detail page (`/owner/repo/symbol/notes/my-note.md`)

A vault note's symbol detail page shows:

Rendered Markdown body (not raw source)
Frontmatter panel: source_type chip, source_id, date, project, tags, entities
History timeline: every agent and human write with full provenance
Linked notes: inbound + outbound references rendered as chips
Consolidation events: highlighted in the timeline with the LLM model that ran them
Attestation badge: ICP anchor hash if present

6.3 Knowledge Proposals

Proposals for vault repos surface as note-level review, not diff-level code review:

Side-by-side note render (before / after)
Frontmatter diff panel (not raw YAML hunks)
Harmony auto-resolution preview: which fields were auto-merged, which escalated
Rubric scoring (imported from Knowtation Hub's proposal rubric)

6.4 Vault search on MuseHub

/owner/repo/symbols?q=agents&domain=knowtation does semantic search (vector) + keyword search across all notes in the vault, returning results ranked by relevance with frontmatter context.

Deliverables: domain-aware repo landing, note detail page, knowledge proposals UI, vault search endpoint.

Phase 7 — Attestation & Unified Provenance Chain

Goal: Muse's Ed25519 commit signing and Knowtation's HMAC attestation converge into a single, optionally ICP-anchored provenance record that satisfies both systems.

7.1 Attestation commit metadata

When --attest is passed to muse commit, the domain plugin:

Computes an HMAC-signed attestation record over the snapshot ID and commit metadata
Embeds the HMAC in commit meta: {"attestation": {"hmac": "...", "algorithm": "sha256-hmac"}}
Optionally calls the ICP canister API to anchor the snapshot ID on-chain

7.2 ICP anchoring as a push hook

muse push local main --attest-icp triggers an ICP canister call after a successful push, recording the branch tip sha256:... on the Internet Computer. The canister tx ID is written back to the commit's meta via muse annotate.

7.3 `muse verify-commit --attest`

Extends muse verify-commit to also verify the HMAC attestation and optionally confirm the ICP anchor matches the commit ID.

7.4 Provenance chain visualisation on MuseHub

Note detail pages show a provenance strip:

🔑 Signed  →  ✦ HMAC attested  →  ⛓ ICP anchored  sha256:4cdd…  tx:0xabc…

Each badge is a link to the verification proof.

Deliverables: --attest flag on muse commit, ICP push hook, muse verify-commit --attest, provenance strip on MuseHub note detail pages.

Implementation order

Phase 1  Domain Foundation          ← must ship first; everything depends on parser/plugin
Phase 2  Semantic Diff & Harmony    ← depends on 1; needed before any multi-agent vault use
Phase 3  Code Intelligence          ← depends on 1 + link indexer; can start after Phase 1 merges
Phase 4  Memory Timeline            ← depends on 2; commit metadata schema
Phase 5  MCP Surface                ← depends on 3 + 4; all tools need intel + timeline
Phase 6  MuseHub UI                 ← depends on 1, 2, 3; note detail needs symbols + diff
Phase 7  Attestation                ← depends on 1; can be worked in parallel with 3–5

Open questions for @aaronrene

Vault detection boundary: Should the domain activate on any .md with Knowtation frontmatter, or only when a config/local.yaml (or .knowtation) marker file is present at the repo root?
Vector index ownership: Knowtation already builds and owns a vector index (data/). Should Muse's code intelligence layer query that index directly, or maintain a parallel index built from commit snapshots? Parallel gives historical search; direct gives freshness.
Consolidation daemon as hook vs. external process: Is it better to invoke the consolidation daemon as a muse merge pre-hook (tight coupling, simpler UX) or to have the daemon watch for new commits and run asynchronously (loose coupling, more robust)?
ICP canister reuse: Knowtation already has a Motoko attestation canister (hub/icp/). Should Muse's attestation layer call that canister directly, or define a generic Muse attestation interface that the knowtation domain plugin implements?
SKILL.md and agent discovery: Knowtation ships .cursor/skills/knowtation/SKILL.md for agent discovery. Should Muse's agent-config system auto-discover this file and incorporate it into the merged agent.md, or keep them separate?

◎ Activity

●

gabriel opened this issue 33 days ago

◎

No activity yet. Use the CLI to comment.

Assignee

aaronrene human

Release

no commits linked to this issue

create

muse hub issue create \
  --title "..." \
  --body "..." \
  --label bug \
  --anchor path/to/file.py::Symbol \
  --commit-anchor <sha> \
  --repo gabriel/muse

read

muse hub issue get 2 --json
muse hub issue list --state open --json

update

muse hub issue edit 2 \
  --anchor path/to/file.py::Symbol \
  --repo gabriel/muse

comment

muse hub issue comment 2 \
  --body "Fixed in <sha>" \
  --repo gabriel/muse

muse hub issue close 2 \
  --repo gabriel/muse

create

create_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  title: "...",
  body: "...",
  labels: ["bug"],
  symbol_anchors: [
    "path/to/file.py::Symbol"
  ],
  commit_anchors: ["<sha>"]
})

read

get_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 2
})

list_issues({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  state: "open"
})

update

edit_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 2,
  symbol_anchors: ["path/to/file.py::Symbol"]
})

comment

create_issue_comment({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 2,
  body: "..."
})

close_issue({
  repo_id: "sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec",
  issue_number: 2
})

create

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{
    "title": "...",
    "body": "...",
    "labels": ["bug"],
    "symbol_anchors": ["path/to/file.py::Symbol"]
  }'

read

# get one issue
curl http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/2

# list open issues
curl "http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues?state=open"

update

curl -X PATCH \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/2 \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{"title": "...", "body": "..."}'

comment

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/2/comments \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\"" \
  -d '{"body": "Fixed in <sha>"}'

curl -X POST \
  http://localhost:10003/api/repos/sha256:200e8689fe34a831289bc1eca17633b2069d595379b7c2f57a158e35d8291bec/issues/2/close \
  -H "Authorization: MSign handle=\"...\" ts=... sig=\"...\""

feat: Knowtation domain — vault-native VCS intelligence for agent knowledge systems

Summary

Why this matters

Phase 1 — Domain Foundation

1.1 File type registration

1.2 Symbol model for vault notes

1.3 .museattributes defaults for vault repos

1.4 muse domain-info output

Phase 2 — Semantic Diff & Harmony Merge

2.1 Section-aware diff

2.2 Harmony policies for common vault conflicts

2.3 Three-way merge for note content

2.4 muse code compare output for vault files

Phase 3 — Code Intelligence over the Knowledge Graph

3.1 Note graph as dependency graph

3.2 Note hotspots and gravity

3.3 Dead note detection

3.4 Clone detection for notes

3.5 Entanglement — notes that always change together

3.6 Velocity per project

Phase 4 — Vault as Agent Memory Timeline

4.1 Memory event types as commit metadata

4.2 muse code symbol-log as memory replay

4.3 Consolidation as a merge transform

4.4 Session bootstrap from commit history

Phase 5 — MCP Domain Surface

5.1 Domain-native MCP tools

5.2 MCP resources

5.3 Prompts

Phase 6 — MuseHub UI for Vault Repos

6.1 Domain-aware repo landing page

6.2 Note detail page (/owner/repo/symbol/notes/my-note.md)

6.3 Knowledge Proposals

6.4 Vault search on MuseHub

Phase 7 — Attestation & Unified Provenance Chain

7.1 Attestation commit metadata

7.2 ICP anchoring as a push hook

7.3 muse verify-commit --attest

7.4 Provenance chain visualisation on MuseHub

Implementation order

Open questions for @aaronrene

1.3 `.museattributes` defaults for vault repos

1.4 `muse domain-info` output

2.4 `muse code compare` output for vault files

4.2 `muse code symbol-log` as memory replay

6.2 Note detail page (`/owner/repo/symbol/notes/my-note.md`)

7.3 `muse verify-commit --attest`