Semantic Curation

This is a field report, not a proposal. It describes what was built after a year of trying the obvious solutions and finding them insufficient for the work at hand.

Working across research, business, and software engineering makes certain failure modes easier to see: it is possible to find accurate information and still make the wrong decision because the full context is missing. The information is correct. The decision is still wrong.

This system was described at an earlier stage in a previous essay, Infrastructure for Intent. Much of what was direction then is concrete now, and some of it has been removed.

The Problem

For a long time, Obsidian was the primary knowledge store. Every organisational scheme was tried: folders, tags, backlinks, indexes, and treating the vault as a graph. Folders alone never carried enough meaning, particularly for project and business work that refuses to remain inside one boundary, although folders remain the physical basis of everything that followed.

Then RAG and vector search were added. Questions returned chunks of notes. The answers were usually accurate in a narrow sense: they quoted something that had been written. But they rarely supplied everything needed to act well. A retrieved chunk does not tell you:

• why a decision was made;
• what changed elsewhere while attention was elsewhere;
• whether an earlier assumption still holds;
• what the surrounding organisational context means for the current situation.

A software example

A concrete example came from Phase 11 of the MagpieCP roadmap, when the service-package activation lifecycle was implemented. The ticket was narrow and well defined. Agents needed to activate, disable, and uninstall service packages with appropriate previews, refusals, APIs, commands, and audit trails. The implementation passed its tests and met the ticket's acceptance criteria.

But review showed that one service had absorbed responsibilities that belonged to several separate primitives. It handled registry storage, preview evidence, audit emission, lifecycle eligibility, required-document handling, and result formatting. It had become a god service. The ticket had been implemented correctly, but the ownership model violated the wider architectural intent of the system. The module had to be decomposed, responsibilities moved to their proper boundaries, and the tests reorganised around that ownership.

By intent fidelity, the feature was complete. By intent integrity, it had failed. The code was correct. The system was slightly worse.

A business example

The same pattern appears in ordinary business decisions. Imagine a sales representative preparing a substantial discount to retain a customer. The CRM record is current, the contract terms are valid, and the discount falls within the normal approval band. Everything visible to the sales process says the offer is reasonable.

What the representative cannot see is that the support team has spent months trying to move the same customer onto sustainable terms, or allow the account to leave, because it consumes more in support effort than it contributes in margin. That context exists, but not in a form available to the sales decision. Accurate data produces the wrong action.

This was the failure mode that kept recurring. It was not simply a search problem. It was a context and continuity problem.

What Was Tried

Obsidian as a graph

Obsidian's graph showed that two notes were linked. It did not show what the relationship meant, whether it still held, or whether one record had superseded another. A graph of files is not automatically a graph of meaning.

RAG and embeddings

Vector retrieval made relevant notes easier to find. But semantic similarity is not the same as operational relevance. A design constraint and a later implementation that violates it may use entirely different language. A decision in one meeting and its reversal six months later may be stored as unrelated fragments. A local exception can resemble a general rule once the surrounding document structure is removed.

Chunking compounds the problem. It divides documents into units suitable for retrieval while weakening chronology, authority, lifecycle, and document-level relationships. RAG was useful for locating related text. It was not a sufficient foundation for preserving intent.

MCP and agent orchestration

MCP was also experimented with. It is a useful integration standard for connecting independent tools and agents, but it was not the right foundation for Magpie's authority and lifecycle layer. Magpie's agents are not independently sovereign clients discovering capabilities. They operate inside one governed system, under its permissions, rules, skills, lifecycle, and orchestration. Adding MCP introduced manifests, adapters, discovery surfaces, and another contract that could drift from the source model. The step back was to typed APIs owned directly by the system. An earlier essay described this orchestration layer in more hopeful terms. It has since been removed.

LLM-maintained wikis and agent memory

Two adjacent approaches are worth distinguishing.

The "LLM-maintained wiki" pattern described by Karpathy (2026) takes raw sources and has an LLM create cross-linked summaries, indexes, and logs. This is more cumulative than ordinary RAG because knowledge is written back into a readable corpus rather than reconstructed for every query. But the readable authority is generated by the model, links do not necessarily carry structured meaning, and freshness, scope, provenance, and review state are not inherently first-class.

Agent-memory systems such as Mem0 (2026) solve another genuine problem: continuity across sessions. They can extract facts from interactions, scope memories, and retrieve them later. But persistent memory for an agent is not the same as a governed knowledge and authority layer for an operation. Most memory systems help an agent remember. What was needed here was a way for learning captured in one session to remain available across later sessions, agent roles, and models.

The Insight

Retrieval was not the hardest problem. The harder problem was maintaining operational meaning over time.

Meaning is also not one thing. Intent integrity is a chain: capture, provenance, authority, freshness, applicability, retrieval. It tends to fail at whichever link is weakest. A system can capture something faithfully and still lose its meaning through staleness, misattribution, incorrect scope, supersession, or simple unfindability.

Documents are not decisions. Notes are not context. A system that retrieves the right document can still leave the user to reconstruct the meaning around it. Much of the most important meaning in an organisation is never written into a formal document at all. It exists in conversations, in the reasoning behind a change, in a decision made informally, or in the assumption that everyone understood but nobody captured.

Two requirements became clear:

1. A human-readable source of truth that can be owned, inspected, and versioned.
2. A way to capture meaning while its full context is still available, so that future agents or future versions of the operator can retrieve it.

The first pointed to local-first Markdown. The second pointed to what is now called semantic curation.

What Was Built

MagpieCP is the kernel that came out of this work. It is a local-first intelligence control plane built around several principles.

• Human-readable Markdown is source authority. Agents can consume structured projections, but humans own the documents.
• Generated retrieval state is derived. Knowledge-base representations, manifests, indexes, graphs, edges, and reports are generated from governed Markdown documents and curation records. They can be rebuilt or invalidated.
• Hub-and-spoke structure. Documents are organised into global zones and project spokes. Material can be promoted from a spoke into a global zone when it becomes broadly useful.
• Semantic curation captures meaning at the time. When a user or agent recognises something worth carrying forward, such as a constraint, lesson, decision, risk, exception, or observation, it is captured with provenance, evidence, state, scope, and applicability.

The document hub contains global zones for shared knowledge, resources, entities, assets, and agent-facing material. Project spokes hold work specific to one domain: a research interest, a development project, a client engagement, a product, or a business department. Documents can move from a spoke into a global zone when they become useful beyond their original context.

Curation is searched across the agent's authorised scope by default, because the relevant intent may not be stored in the same spoke as the current work. Narrowing to a domain, project, or spoke is a retrieval filter, not a prerequisite.

Two Complementary Knowledge Systems

Magpie contains two related but distinct knowledge systems.

The knowledge base

The knowledge base represents the governed document estate. Every eligible Markdown document has a structured JSON representation. Graphs and edge files are generated across those representations to support retrieval, navigation, validation, and relationship analysis.

The knowledge base helps answer questions such as:

• What exists?
• What does the governed record say?
• How does it relate to other records?
• What may be affected by a change?
• Are its generated projections still current?

The Markdown remains human-owned source authority. The JSON representations and graph structures are derived and can be regenerated.

Semantic curation

Semantic curation represents knowledge accumulated while work is happening. Each curation is a governed record of something worth carrying forward: a decision, constraint, lesson, risk, observation, interpretation, exception, pattern, or other operational meaning. A manifest, graphs, and edge files are generated from those curation records for retrieval.

The knowledge base represents what has been documented. Semantic curation preserves what the human-agent system has learned.

A curation does not belong to one conversation, one temporary agent role, or one model. Once captured and governed, it becomes part of the local shared knowledge layer. Knowledge preserved by a researcher can later be encountered by an implementer. A reviewer can retrieve the reasoning behind a decision without reconstructing it from old conversations. The same underlying model may perform those roles, or another local or cloud model may be used where appropriate. The important point is that the learning persists outside the session and outside the model that first encountered it.

Sessions end. Agents change. Models are replaced. The accumulated understanding of the operation remains.

The distinction is not between retrieval and no retrieval. Both systems use generated structures for retrieval. The difference is in what their underlying records preserve: the knowledge base represents governed documents, while semantic curation preserves learning captured during the work.

Retrieval is also governed rather than left entirely to agent discretion. Agents are expected to consult curation at defined points: when a session begins, before governed work is activated, before implementation starts, and before work is closed. Queries are shaped by current intent rather than issued as unconstrained memory dumps. Retrieved curation is not treated as source authority: if it would materially affect governed state, source documents, or money, the agent must follow it back to its evidence or authoritative source before acting.

Capturing Meaning at the Time

The critical design choice is not merely what gets stored. It is when meaning is captured.

Semantic relationships cannot be maintained reliably by mechanically analysing a completed corpus after the fact. A system may infer that two documents are similar. It cannot safely determine from similarity alone why they are related, whether the relationship remains active, which direction it runs, or whether it represents a dependency, an exception, a governing rule, a conflict, or a historical connection.

Those judgements are easiest and most reliable while the context still exists. When a document is created, Magpie's tooling selects the appropriate type, generates the required structure and front matter, and fills fields that can be known mechanically: identifiers, timestamps, provenance, lifecycle defaults, and schema-controlled values. Semantic and relationship fields require judgement. They express what the document relates to, what governs it, where it applies, and what else may be affected. Those fields are completed by the user or agent during creation or material editing, while the relevant conversation, documents, purpose, and reasoning are still available.

The same principle applies to semantic curation. A decision, constraint, risk, or lesson can be preserved while the why, what, where, when, evidence, applicability, and possible limits are still present. Capture is designed to be frictionless enough to happen during the work rather than as a later knowledge-management exercise.

But capture alone is not enough. A record created at the right time can still become useless if it cannot later be trusted, scoped, or found. Curations therefore carry provenance, evidence, scope, lifecycle state, and supersession. A record can distinguish what was observed directly, derived from conversation, linked to source material, or confirmed by the operator. For lessons learned from experience, the system separates:

• what should be remembered;
• why it mattered;
• what future agents should do differently;
• where the lesson may be wrong, incomplete, or overgeneralised.

Recording doubt matters. A system that captures the limits of its own learning gives future agents a reason to recheck before relying on it.

Governance Without Burdening the User

Drift has been the persistent problem beneath all of this:

• An implementation can drift from a ticket while still appearing complete.
• A document can remain individually valid while no longer agreeing with related records.
• A JSON projection or graph can become stale against its source.
• An agent can preserve the wording of an instruction while losing the wider architectural or organisational intent behind it.

Humans do this too. AI can make the problem faster and less visible because it produces coherent-looking output even while the underlying intent is gradually diverging.

Magpie therefore places deterministic guardrails around durable state. It does not try to make agent reasoning deterministic. Users and agents can converse, explore, draft, create, and edit naturally. The checks happen when that work becomes part of the governed system:

• Documents are checked for valid structure, required front matter, identifiers, locations, lifecycle rules, and permitted values.
• Semantic relationships are authored contextually, but their references and forms can still be validated.
• Knowledge-base projections, curation manifests, graphs, and edge files are checked for freshness against their sources.
• Agent actions are checked against permissions, role, scope, installed skills, and system invariants.

This does not prove that document content is true or that every judgement is correct. Deterministic checks cannot validate meaning itself. They can prevent malformed, stale, unauthorised, or internally inconsistent state from being accepted silently.

Intent integrity is the property being protected. Drift is the force degrading it. Guardrails are the enforcement mechanism. Most of this remains transparent to the user: they can create and edit documents, converse with an agent, and work through decisions without manually operating the governance machinery.

From a Vault to an Operating Environment

The system began as a governed document vault. Over time, the boundary between document management and operational software proved thinner than expected. A significant proportion of personal and small-business operational state can be represented as structured, human-readable records:

• project tickets;
• decisions;
• action items;
• time records;
• invoices;
• meeting outcomes;
• procedures;
• research notes;
• client context;
• operational logs.

The aim is not to pretend that every specialist application can or should disappear. It is to ensure that information contributing to operational context has a governed representation in the shared system. Tickets should not become invisible because they live in a project-management application. Decisions should not become disconnected because they were made in email. Procedures should not be isolated from the work they govern, and important reasoning should not exist only in a person's memory or a temporary agent conversation. Application boundaries should not determine which knowledge can be related.

Removing silos, not separation

Access boundaries still matter. Some information must remain limited by role, client, project, or policy. Removing silos does not mean removing legitimate separation. It means that authorised information can participate in one connected context and intent pool rather than being fragmented across folders, departments, applications, and sessions.

Material also arrives as PDFs, Word documents, email attachments, images, and other binary formats. Where the original artefact must be retained, it is stored separately in a non-Git-controlled asset zone. A Markdown record can then become the governed operational representation, carrying provenance, lifecycle state, relationships, and a link back to the original source.

Higher-level capabilities can use the same foundation. Spokes may support action items, governed work tickets, time records, billing, or other lightweight services without isolating their context in separate proprietary systems. The objective is not to recreate every business application in Markdown. It is to keep the context and intent surrounding the work connected.

The workspace layer

The BOS layer is being developed as a thin workspace over this kernel: conversation at the centre, with document browsing, lists, tickets, and operational views around it. The operator talks to one manager or orchestrator agent, which can assign temporary roles such as researcher, implementer, or reviewer. In ordinary use, one or two models may perform most of those roles, locally or through cloud services. In daily use, those roles have settled into named agent personas: Grace handles development, Kimi handles writing and the website, and Hamilton manages specific client project work. They are named roles, not people.

The models provide cognition for the work. They do not own the knowledge, rules, or accepted state produced by it.

Agent-Facing Knowledge and Skills

The global hub includes an Agents zone containing governed source material for agents: skills, procedures, role definitions, operating instructions, and behavioural constraints. These documents are not necessarily the artefacts consumed directly at runtime. Skills can be installed in forms optimised for the particular model or role that will use them. Magpie governs which version is installed, when it may be invoked, under what scope, and subject to which rules.

This separates stable operational intent from model-specific execution. A skill may have different optimised implementations for different models while its purpose, constraints, provenance, and permitted use remain governed by the same system.

The agent-facing material is itself subject to the same intent-integrity problem as any other operational context. Instructions can accumulate, duplicate, contradict, and become difficult for agents to follow. The cohesion rule violated by the god service described earlier already existed when that service was built. Instructions that exist are not instructions that are followed, and adding more instructions in more places makes adherence worse, not better.

Magpie therefore also measures and governs the instruction surface agents actually receive. The first measurement found that the material an agent loads before a session has even started ran to roughly 283,000 characters. The system identifies duplicated, overlapping, and conflicting instructions and streamlines their placement under human review, replaying accepted changes before they are retained. A companion note, Measuring the Agent Surface, describes the method.

Curation is routed into that context only where relevant, rather than loaded indiscriminately. The same principle applies on both sides: what an agent is told, and what the operation has learned. Both are governed. Both can drift. Both must remain scoped and retrievable.

Why Local-First Matters

Local-first is the right default for this kind of personal and small-business context. Documents, decisions, relationships, financial records, operational history, and accumulated agent knowledge should not depend entirely on a model provider or SaaS vendor remaining available.

Local-first does not mean offline-only. External models and services can still provide compute or specialist capabilities. It means the authority, lineage, and accumulated knowledge remain under the operator's control. This transfers responsibility for backup, synchronisation, access control, and availability to the operator. That is a real trade-off.

But if a model changes, a provider changes, or a service disappears, the governed records remain. Agents are replaceable cognition providers. The intent stays local.

Known Boundaries and Open Questions

This is not claimed to be solved. The system is in daily use, but it is not finished. The hub it manages is also the environment in which it is being built, so every ticket, session, decision, and failure contributes evidence about the design. Several boundaries and open questions remain.

• Scale. The current filesystem, JSON, manifest, and graph approach is intended to remain responsive for hubs of at least around 1,000 documents and potentially several thousand. When filesystem scanning and generated projections stop being the simplest appropriate mechanism, the storage layer will move to SQLite.
• Retrieval quality. The query engine is currently deterministic and relationship-based. Hybrid retrieval combining semantic similarity, keyword matching, and entity linking may improve discovery, but it risks reintroducing opacity.
• Curation selectivity. Capture must remain useful rather than exhaustive. The system still needs to preserve consequential learning without turning every observation into permanent operational knowledge.
• BOS usability. The business operating layer is still early. Hiding the kernel's complexity without hiding its integrity constraints remains a difficult design problem.
• Applicability to others. The system was built around my own work first. Whether the same balance of structure, curation, governance, and flexibility works for people with different workflows remains open.

Some safeguards are already established rather than speculative. Curations carry provenance, scope, evidence, state, and supersession. Access rules constrain retrieval. A query may indicate that relevant material exists but is inaccessible, while preventing content from restricted areas from leaking into the result. Shared context does not mean unrestricted context.

What You Might Take From This

If you are building or choosing a knowledge system, several questions are worth asking:

1. Does the system preserve operational meaning, or only documents and retrieved passages?
2. Can a future agent, or a future version of you, understand why a decision was made?
3. Can knowledge captured in one session be used safely in later sessions, by other agent roles, and by other models?
4. Are semantic relationships captured while their context exists, or inferred later after much of that context has disappeared?
5. Who owns the source authority if the model, vendor, or application disappears?
6. What prevents locally reasonable changes from producing long-term drift?

Retrieval remains useful. Embeddings remain useful. Standard protocols remain useful in the environments they were designed for. But they should not be mistaken for authority, continuity, or understanding.

The progression for Magpie has involved both construction and removal: from disconnected documents to governed relationships; from retrieval to shared semantic curation; from session-bound model context to persistent local knowledge; from general-purpose agent protocols back to system-owned APIs and deterministic boundaries.

The fashionable tools were not necessarily wrong. They were not enough. Some of them were solving problems this system did not need to have.

References

Karpathy, A. (2026). llm-wiki. GitHub Gist. https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

Mem0. (2026). AI agent memory layer for agents and apps. Mem0. https://mem0.ai/