ksor
Health Gecti
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 135 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
KSoR (Knowledge System of Record) is an open-source SDK for building governed, authoritative knowledge systems for humans and AI agents. It is a foundation of an AI-native knowledge platform.
Watch the video: KSoR Introduction
KSoR
Open, vendor-neutral knowledge infrastructure for predictable enterprise and education agentic systems.
A company cannot expect predictable AI-agent behavior if its agents operate from scattered, conflicting, or outdated knowledge.
An education institution cannot deliver an organized AI-assisted course if its tutors, teaching assistants, and assessment agents operate from different curricula, sources, or rules.
You cannot build predictable AI systems on an undefined source of truth.
A Knowledge System of Record (KSoR) solves that problem by giving an organization one governed, authoritative knowledge record that humans and AI agents operate from.
For an enterprise, that record can contain approved:
- policies,
- procedures,
- rules,
- methods,
- standards,
- definitions,
- controls,
- decision criteria,
- and institutional knowledge.
For an education institution, it can contain approved:
- curriculum,
- learning objectives,
- concepts and definitions,
- pedagogy,
- course sequence,
- source material,
- assessment rules,
- grading criteria,
- and the current course version.
The AI can still reason, explain, personalize, and adapt. What it should not have to invent is which institutional or academic knowledge is authoritative.
Enterprise agents need a KSoR so they operate from the same governed institutional truth.
Education agents need a KSoR so they teach from the same governed academic truth.
KSoR does not make a probabilistic language model deterministic. It makes the knowledge environment governed, bounded, traceable, and testable: which source is authoritative, which version is current, who approved it, who may see it, which knowledge may be retrieved, and when an agent must abstain instead of improvising.
The framework reduces to three commitments:
One authoritative record.
One governance boundary.
Many open projections.
And one operating principle:
Govern knowledge once. Project it many ways.
The result is not merely a documentation site, knowledge base, vector database, RAG system, or MCP wrapper.
KSoR is an open knowledge infrastructure framework that makes governed knowledge usable by people, AI agents, and other knowledge systems without giving any one vendor ownership of the record.
KSoR in eight concepts →
17 slides, one hospital, plain language, no code. One authoritative record, what belongs in it, provenance, the governance boundary, abstention, citation, how new knowledge gets approved, and the many open projections that read it — the deck to open when you are introducing KSoR to a team.
Start here
All you need is Node 24 or newer. Use whichever package manager you already
have — npm, pnpm, or bun — and the project it creates will use that same
manager everywhere:
npm
npx @panaversity/ksor@latest init my-knowledge-sor
cd my-knowledge-sor && npm install && npm run dev
pnpm
pnpm dlx @panaversity/ksor@latest init my-knowledge-sor
cd my-knowledge-sor && pnpm install && pnpm dev
bun
bunx @panaversity/ksor@latest init my-knowledge-sor
cd my-knowledge-sor && bun install && bun run dev
Open http://localhost:3000. The site is running, and it reloads as you edit
the Markdown files in knowledge/. What you have is a complete, ordinary
project — a working website, a CI workflow, and instructions for coding agents
— and it is entirely yours: nothing is downloaded at build time, and nothing
phones home. The five documents in it are KSoR's own starters, there to be
deleted as your knowledge arrives.
Ask it to publish and you meet the point of all this:
$ pnpm exec ksor build
ksor build: 6 document(s), 5 admitted to a machine surface
Six documents, five admitted. The one you just wrote is a draft, so it
reaches no surface an AI agent reads — not llms.txt, not the markdown twins,
nothing — until a human approves it. Approve it and the count moves.
Hello world walks that end to end in
about fifteen minutes, from an empty directory to your own coding agent
answering from your own document and naming which document and which
publication it came from. Every command and output in it was run and pasted as
it appeared.
The three so far, in reading order — pick by what you want from it:
| read this if | |
|---|---|
| 00 · Introduction | you want to understand why this exists — no technical background needed |
| 01 · Hello world | you want to see it work in fifteen minutes — Node only, nothing else |
| 02 · Make it yours | you finished hello world and want a record that is only yours — a file in, a person's knowledge in, the samples out |
Next, open the project in the coding agent you already use (Claude Code,
Cursor, Copilot — any of them) and tell it what this knowledge base is
for. That is how you work with KSoR day to day: you write plain Markdown,
in whatever language you write in, and the agent handles the checks and
structure around it. The project ships AGENTS.md with the working rules,
and the agent will interview you to replace the placeholder in instance.md
— the file that says what this knowledge base covers.
Later, when you want AI agents to query your knowledge directly, you add
a Postgres database and an embedding API key, then run three commands:pnpm provision once, pnpm refresh to publish, and pnpm serve. The full
path is in Serve to AI Agents below.
The rest of this page explains why KSoR is built this way. To go straight
to the practical reference, jump to Requirements.
Why KSoR Exists
Organizations already understand the value of a System of Record.
An accounting system is authoritative for financial transactions. A CRM is authoritative for customer records. An HRIS is authoritative for employee records.
When a spreadsheet disagrees with the accounting ledger, the ledger wins.
These systems answer:
What is the authoritative operational state of the organization?
AI agents create a second requirement:
What is the authoritative knowledge the organization allows them to operate from?
That includes questions such as:
- What policies apply?
- What rules govern this decision?
- Which procedure should be followed?
- What does this organization mean by this term?
- Which thresholds are approved?
- Which methodology should be used?
- What exceptions exist?
- What sources support this answer?
- What should the agent do when the answer is not known?
In education, the same authority problem appears in a different form:
- What curriculum is current?
- Which learning objectives govern this course?
- Which definitions and explanations are canonical?
- Which sequence should be taught?
- Which sources are approved?
- Which assessment and grading rules apply?
- What may an AI tutor personalize, and what must remain fixed?
Without a KSoR, this knowledge is commonly fragmented across documents, wikis, PDFs, slide decks, websites, instructor notes, repositories, prompts, RAG indexes, model context, and human memory.
A model can rank what looks relevant. It cannot reliably manufacture organizational or academic authority when the institution itself has not defined it.
The problem is not simply finding knowledge. The problem is establishing which knowledge wins.
KSoR exists to establish that authority and make it usable across human, AI, agent, and machine-facing surfaces.
Predictable AI Needs a Knowledge System of Record
The more autonomy an AI agent receives, the more important its knowledge boundary becomes.
KSoR separates two things that are often confused: model variability and knowledge authority. Models may vary in wording, reasoning paths, explanations, and personalization. The authoritative knowledge they are permitted to use should not vary arbitrarily.
KSoR makes that knowledge environment controlled and testable:
- which knowledge is authoritative,
- which version is in force,
- who owns and approved it,
- which audience may see it,
- which sources support it,
- what retrieval is permitted,
- and when the system must abstain.
That distinction matters in both enterprises and education.
In an enterprise
Without a Knowledge System of Record, an agent may encounter several plausible sources:
AI Agent
│
┌────────────┬───────┼────────┬─────────────┐
▼ ▼ ▼ ▼ ▼
old wiki current Slack stale RAG model memory
policy message chunks
│ │ │ │ │
└────────────┴───────┼────────┴─────────────┘
▼
Which source should win?
The agent can rank relevance. It cannot manufacture organizational authority.
With a KSoR:
Governed KSoR
│
authoritative knowledge
│
governance boundary
│
▼
AI Agent
│
▼
predictable, bounded action
The agent may still reason probabilistically, but it reasons from a controlled institutional truth rather than choosing among conflicting versions of that truth.
A company cannot build predictable agentic operations on unpredictable knowledge.
In education
The same problem appears when AI agents become tutors, teaching assistants, assessment agents, or curriculum assistants.
Without an authoritative academic record, two students in the same course can be taught from different model memory, different web sources, different editions of course material, or outdated instructor notes. Personalization then becomes curricular inconsistency.
An education KSoR can govern the academic truth:
Education KSoR
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Curriculum Pedagogy Assessment
│ │ │
└─────────────────┼─────────────────┘
▼
governed course record
│
┌─────────────┼─────────────┐
▼ ▼ ▼
AI Tutor Teacher AI Assessment AI
The AI can still adapt:
- explanation,
- examples,
- pacing,
- language,
- difficulty,
- practice,
- and remediation.
But the KSoR can keep stable:
- learning objectives,
- canonical concepts and definitions,
- prerequisites,
- approved source material,
- course sequence,
- assessment rules,
- grading criteria,
- and the current course version.
Personalization should vary the teaching path, not the authoritative curriculum.
An education institution cannot run an organized AI-assisted class if every tutor or teaching agent is free to choose a different source of truth.
So the same architectural principle applies in both settings:
Enterprise agents need a KSoR so they operate from the same governed institutional truth.
Education agents need a KSoR so they teach from the same governed academic truth.
The KSoR Framework: Nine Responsibilities
The product idea is simple:
- one place defines the knowledge,
- governance decides what is authoritative and who may use it,
- open interfaces make the same governed truth available wherever it is needed.
The technical architecture implements that idea through an open, vendor-neutral knowledge infrastructure framework, built around three commitments:
One authoritative record.
One governance boundary.
Many open projections.
That model in one picture:
KSoR FRAMEWORK
open, vendor-neutral knowledge infrastructure
│
AUTHORITATIVE CORE
Governed Markdown
(KSoR Profile of OKF)
│
GOVERNANCE BOUNDARY
│
┌──────────────┬───────┴───────┬──────────────┐
│ │ │ │
▼ ▼ ▼ ▼
Human site AI discovery Agent surface Exchange
Fumadocs llms.txt MCP governed OKF
│ bundles
▼
Retrieval layer
Postgres + pgvector
Identity (OAuth/OIDC) cuts across every surface. Publication integrity
(SLSA/Sigstore) covers the published PACKAGE and not yet the record's own lock,
and observability (OpenTelemetry) is bound and unbuilt — see below, where both
are stated exactly.
The nine responsibilities
The framework separates nine responsibilities, so that no single product
becomes the knowledge authority. Wherever an open format, convention, or
protocol already owns a boundary, KSoR adopts it rather than competing with
it:
| Responsibility | Open standard / reference binding | What it means |
|---|---|---|
| Authoritative record | Markdown in the KSoR Profile of OKF | Markdown is the durable medium; the profile gives it open, portable structure |
| Retrieval | Postgres + pgvector | structured, lexical, and semantic search over the governed record |
| Human publication | Fumadocs | the reference human-readable site |
| AI discovery | llms.txt |
tells AI systems what knowledge exists and where machine-readable pages are |
| Agent interaction | MCP | search, retrieval, citation, and abstention for agents |
| Knowledge exchange | OKF | the same native representation moves governed knowledge between systems |
| Identity | OAuth / OIDC | who is asking — KSoR governance then decides what they may see |
| Publication integrity | SLSA / Sigstore (package only) | proof of which source and build produced a published artifact |
| Observability | OpenTelemetry (not yet emitted) | what the infrastructure did, without becoming another knowledge store |
One of the nine is a binding with nothing behind it yet, and one is half
built — both say so here. ksor build
writes build.lock.json but signs nothing — SLSA/Sigstore attestation of that
lock is out of scope in specs/ksor/build/spec.md §5 and will land separately.
No telemetry is emitted today either: there is no OpenTelemetry code in the
tree, and the row above records which standard owns that boundary rather than a
surface that runs. When it does land, one constraint is already decided by the
row's own wording — without becoming another knowledge store. Default
auto-instrumentation would break it immediately, because pg captures statement
text and a trace backend is a different security boundary from the MCP response;
for a non-public audience that is a governance bypass through the observability
layer. What would survive careless instrumentation added later is an allowlist
span processor — attributes not explicitly permitted are dropped, so traces
would carry decisions and counts and never content.
The same architecture can be explained as a dependency stack. This is not a second list of responsibilities; it shows how the pieces relate, and why OKF sits under KSoR rather than beside it:
Markdown is the authoritative medium.
OKF makes that record open and portable.
KSoR governance makes it authoritative.
Postgres + pgvector make it retrievable.
Fumadocs serves humans.llms.txtlets AI discover it.
MCP lets agents interact with it.
OAuth/OIDC establishes identity; KSoR governs access.
SLSA/Sigstore proves what package was published; the record's lock is next.
OpenTelemetry will tell us what happened.
Governance is deliberately not one of the nine. It is the boundary the
nine are arranged around: no knowledge crosses a serving or publication
boundary without first passing the applicable governance decision. For a
static build that decision runs once per audience-specific build; for dynamic
retrieval it runs per request; the policy is the same either way.
The governance boundary is what turns a set of useful technologies into a
Knowledge System of Record. Without it, the components above would merely
form another knowledge stack.
And the boundaries — not the products — are the standard. Postgres + pgvector
and Fumadocs are reference implementation choices; a conformant alternative
may replace them. What may not vary is the governance semantics: one policy,
every surface.
The full specification — the profile, the conformance classes, the
governance requirements — is the KSoR Standard Proposal
(KSP-001), an open
standard written so that anyone can implement a conformant KSoR. It defines
five conformance classes — a corpus (A), a publisher (B), a retrieval layer
(C), an agent surface (D), and exchange (E) — plus optional profiles for
identity, publication integrity, and computation attestation. A complete
KSoR implements all five classes; a partial implementation (a corpus linter,
say) is valid too, and states its class.
Which of the nine responsibilities the shipped tool implements today is
recorded in docs/status.md — always the authority, never
inferred from this section.
What Is a Knowledge System of Record?
A Knowledge System of Record — KSoR — is the authoritative, governed knowledge layer that humans, AI agents, and software use to understand, decide, and act.
It can contain:
- domain knowledge,
- policies,
- procedures,
- rules,
- standards,
- methods,
- definitions,
- decision criteria,
- thresholds,
- specifications,
- controls,
- examples,
- exceptions,
- workflows,
- provenance,
- and supporting source material.
The goal is not merely to make information searchable.
The goal is to establish:
This is the knowledge we operate from.
Traditional SoR vs. KSoR
A traditional System of Record and a Knowledge System of Record solve different problems.
| Traditional System of Record | Knowledge System of Record | |
|---|---|---|
| Primary purpose | Record operational state | Record institutional knowledge |
| Typical contents | Transactions, balances, customers, employees, inventory | Rules, policies, methods, procedures, standards, definitions |
| Typical systems | ERP, CRM, HRIS, accounting system | KSoR |
| Core question | What is true right now? | What do we know and how should we operate? |
| Optimized for | Applications and business processes | Humans, AI agents, and software |
| Authority | Operational data | Governed knowledge |
| Change mechanism | Transactions | Review, governance, versioning |
| AI role | Tool consumer | First-class knowledge consumer |
AI-native organizations need both.
AI Agent
│
┌──────────────┴──────────────┐
│ │
▼ ▼
Knowledge System Traditional
of Record Systems
(KSoR) of Record
│ │
"How should I "What is true
operate?" right now?"
│ │
Rules · Policies Customers · Orders
Methods · Standards Balances · Inventory
Procedures · Specs Transactions · State
A capable enterprise agent may read policy from a KSoR, retrieve current account data from a CRM, apply the governed rule, execute an action, and record the resulting state back into the traditional SoR.
KSoR Is More Than a Knowledge Base
A knowledge base stores information.
A KSoR establishes authority.
That distinction matters.
A conventional knowledge base may optimize for:
- storage,
- search,
- retrieval,
- similarity,
- document discovery,
- or question answering.
A Knowledge System of Record must additionally answer:
- Who owns this knowledge?
- Where did it come from?
- Which version is authoritative?
- Has it been reviewed?
- What is its scope?
- What happens when sources conflict?
- Can an AI distinguish evidence from inference?
- Can an answer be traced back to its source?
- What should happen when the KSoR does not contain the answer?
KSoR therefore treats governance, provenance, citations, versioning, and abstention as architectural concerns rather than optional features.
Retrieval Is Not the Product
KSoR may use search, indexing, embeddings, full-text retrieval, structured lookup, or other retrieval techniques.
Those mechanisms are implementation details.
KSoR is not fundamentally:
- a vector database,
- an embedding service,
- a RAG framework,
- a chatbot,
- a document search engine,
- or an MCP wrapper.
Those technologies can help deliver a KSoR.
They do not make something a KSoR.
The defining property is authoritative governed knowledge.
Retrieval is one responsibility of nine (The KSoR
Framework); the record, and the
governance boundary around it, are what define a KSoR.
One Source. Multiple Projections.
KSoR follows a simple principle:
Humans, AI agents, software, and other knowledge systems should not operate from different versions of organizational knowledge.
The governed record is the authority. Every outward surface is a projection or controlled interface over that record rather than a separately maintained knowledge store.
Governed Record
Markdown + KSoR Profile of OKF
│
▼
GOVERNANCE BOUNDARY
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
Humans AI Discovery Agents
Fumadocs llms.txt MCP
│
▼
Retrieval layer
Postgres + pgvector
│
▼
Knowledge Exchange
OKF
OAuth/OIDC establishes identity for protected surfaces, KSoR governance controls access, SLSA/Sigstore can attest what was published, and OpenTelemetry will record what the infrastructure did.
These surfaces have different jobs:
- Fumadocs serves people.
llms.txthelps AI systems discover the record.- MCP lets agents search, retrieve, cite, and abstain against governed knowledge.
- OKF gives the authoritative record its open, portable structure and lets knowledge systems exchange governed knowledge.
- Postgres + pgvector is the reference retrieval implementation behind the agent surface.
A KSoR can also carry an agent-first maintenance context such as AGENTS.md and reusable skills. That context tells coding agents how to work on the governed record safely. It is development infrastructure, not a projection and not authoritative knowledge.
The human experience is not maintained as a separate knowledge source.
The MCP interface is not an invisible copy of the website.
Machine-readable outputs are not another knowledge store.
They are different ways of reaching the same governed source.
The Trust Ladder
Not every way of serving knowledge gives the same guarantee, and a KSoR
refuses to pretend otherwise. The trade is explicit, as a ladder: wider
reach means weaker guarantees.
| Rung | Channel | Reach | Guarantee |
|---|---|---|---|
| 1 | Discovery — the site, llms.txt, per-page Markdown |
any AI system can read them | content passed the governance filter when published; nothing after that — no citation discipline, no abstention, no freshness check at answer time |
| 2 | Governed interaction — MCP | AI agents doing organizational work | retrieval filtered by governance before ranking, results cited and traceable to a generation, abstention enforced |
| 3 | Computation attestation — proposed, experimental | specific critical numbers | a reported value was produced by the sanctioned computation and mechanically checked, or it is not shown at all |
The ladder, not any single rung, is the product. It also answers an honest
objection: a system built on citation-before-confidence can still ship a
corpus file that is downloaded once and never checked again — because that
file's rung is stated and its limits are not hidden. Which knowledge needs
which rung is a decision the organization makes, not the tooling.
Core Principles
1. One Authoritative Source
Knowledge should have one canonical location.
Different consumers may receive different representations, but those representations must derive from the same source.
2. Humans, Agents, and Software Are First-Class Consumers
Knowledge architecture can no longer assume that only people will read documentation.
Every important piece of institutional knowledge should be usable by:
- humans,
- AI assistants,
- autonomous agents,
- agent workflows,
- applications,
- and machine-readable tooling.
Different consumers may require different representations, but those representations should derive from the same governed record.
3. Provenance Matters
An answer is much more useful when you can determine:
- what document it came from,
- which version was used,
- when it was built,
- and what source supported the claim.
KSoR preserves the chain from source knowledge to generated projections.
4. Citation Before Confidence
An AI sounding confident is not evidence.
KSoR is designed around traceable answers.
The agent should be able to identify the knowledge that supports its answer rather than relying on model memory.
5. Abstention Is a Feature
A governed AI system needs to know the boundary of its knowledge.
When the KSoR does not contain enough information to support an answer, the correct behavior is:
The Knowledge System of Record does not contain enough information to answer this.
—not improvisation.
6. Governance Before Retrieval
Retrieval technology is not the hard part.
A perfectly optimized search system over ungoverned knowledge simply retrieves ungoverned knowledge faster.
The more important questions are:
- What belongs in the KSoR?
- Who can change it?
- What constitutes an authoritative source?
- How are conflicts resolved?
- How are changes reviewed?
- What is obsolete?
- What requires human judgment?
KSoR treats those questions as fundamental.
And one rule binds every surface: no knowledge crosses a serving or
publication boundary without first passing the applicable governance
decision.
7. Vendor Neutrality
Your institutional knowledge should not belong to an AI model vendor.
KSoR keeps the knowledge layer independent from the model layer.
The mechanism is open standards at every boundary — OKF for the record, MCP
for agents, OAuth/OIDC for identity, SLSA/Sigstore for provenance — with the
reference components behind each boundary replaceable. KSoR invents no
format and no protocol where an open one exists.
The same governed knowledge should be usable from:
- ChatGPT,
- Claude,
- coding agents,
- agent frameworks,
- custom applications,
- Digital FTEs,
- and future AI runtimes.
Models can change.
Your institutional truth should remain yours.
What Can You Build with KSoR?
KSoR is intentionally not limited to a particular industry or type of knowledge.
Organizational KSoRs
Examples:
Agent Factory KSoR
Engineering KSoR
Product Management KSoR
Company Operations KSoR
Security KSoR
AI Governance KSoR
University KSoR
School KSoR
Education KSoRs
Examples:
University Curriculum KSoR
Degree Program KSoR
Course KSoR
Faculty Teaching KSoR
Assessment KSoR
Professional Certification KSoR
An education KSoR lets AI tutors, teaching assistants, and assessment agents personalize instruction while remaining grounded in the same approved curriculum, learning objectives, source material, course sequence, and assessment rules. The teaching can adapt to the student without allowing the authoritative course itself to drift from student to student.
Domain KSoRs
Examples:
Accounting KSoR
Government Contracting KSoR
Healthcare KSoR
Legal KSoR
Banking KSoR
Insurance KSoR
Supply Chain KSoR
Sales KSoR
Product or Method KSoRs
Examples:
Design System KSoR
API Standards KSoR
Architecture KSoR
Implementation Method KSoR
Compliance Framework KSoR
Operating Model KSoR
The SDK does not impose verticality.
A Vertical KSoR is simply one application of KSoR: an authoritative knowledge layer for a particular profession, industry, or domain.
Example
Imagine an Accounting KSoR containing:
knowledge/
├── accounting-policies/
│ ├── revenue-recognition.md
│ ├── capitalization.md
│ └── bad-debt.md
├── procedures/
│ ├── month-end-close.md
│ └── journal-entry-review.md
├── controls/
│ ├── segregation-of-duties.md
│ └── approval-thresholds.md
├── definitions/
│ └── glossary.md
└── examples/
└── revenue-recognition-examples.md
An employee can browse those documents through the generated website.
An accounting agent can access the same governed knowledge through MCP.
If asked:
Can this $42,000 software implementation cost be capitalized?
the agent should retrieve the organization's capitalization policy, apply the relevant criteria, cite the governing source, and distinguish between what the KSoR states and any reasoning required to apply it.
If the capitalization policy does not address the situation, the system should not invent a policy.
Quick Start
Status:
ksor initworks,ksor buildchecks the record and writes its
lock,ksor migraterewrites a pre-profile record into the profile, andksor serveruns the MCP server over a built record (withingest/schema/calibrate/gc— the climbed rung, needing Postgres and a
provider key). Onlydevremains designed, not yet implemented — it prints
an honest notice and exits2; the scaffold's ownpnpm devcovers local
work until it lands.ksor build --bundlesis likewise designed and exits2.docs/status.mdis authoritative on which of these
are in the RELEASED version.
Requirements
Node.js 24 or newer, and the package manager you already use — pnpm, npm, or
bun. ksor init emits the scaffold for whichever one runs it; nobody
installs a second package manager to open their own knowledge base.
node --version
Creating a project, running the site locally, and building it are covered in
Start here at the top of this page — this section continues
where it leaves off.
Serve to AI Agents
First tell instance.md which environment variable holds your DSN — never the
DSN itself. This block is the one piece of configuration the served rung needs:
database:
dsn_env: KSOR_DB_URL
Then fill in the environment and bring it up — three steps, deliberately
separate:
cp .env.example .env # KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH=disabled-local
pnpm provision # ONCE: apply the schema, authorize this tenant to ingest
pnpm refresh # PUBLISH: ingest knowledge/ into a generation, collect old ones
pnpm serve # SERVE: the MCP server, over what you just published
They are separate on purpose. Applying DDL and granting ingest are acts an
operator performs once; publishing is the act a system of record exists to
make deliberate, not a side effect of starting a server. Re-run pnpm refresh
whenever you have edited knowledge/ — everything is re-runnable, and an
unchanged corpus costs nothing.
That serves MCP at http://127.0.0.1:8080/mcp, announcing its posture as it
boots — an uncalibrated record says so in as many words:
auth DISABLED — 127.0.0.1 only, and a public bind will refuse to boot
abstain OFF — no floor calibrated; out-of-corpus questions will be answered, not refused
ksor calibrate measures a floor against your own corpus and prints the two
lines to paste into instance.md; the banner then readsabstain floor 0.609 — below it, this record abstains.
Skip pnpm refresh and the server comes up with nothing published: every search
answers ok: false, reason: "unpublished" — the record is empty, which is a
different answer from "not in the record".
The agent projection exposes the governed KSoR through MCP: search, outline,
and read over stateless Streamable HTTP, with cited passages, snapshot
generation-pinning, and honest abstention. serve reads ./instance.md and
runs the MCP server in-process — the climbed rung, so it needs a Postgres store
(pgvector) and an embedding provider key. It refuses to boot
unauthenticated — a local run declares KSOR_AUTH=disabled-local (which.env.example already carries) and binds loopback, where auth off is the
intended development shape. A public bind needs a configured SSO door instead,
or an explicit KSOR_AUTH=disabled-public.
pnpm serve is the only command this rung needs: run it the first time, after
editing knowledge/, or to bring the server back. Every step reports the state
it found instead of failing, and a rerun on an unchanged record costs nothing —
ingest compares what it read against the generation already serving and, when
they match at the same commit, writes no rows at all. The abstention gate stays
off until you measure a floor with ksor calibrate and paste it intoinstance.md — never copied from another corpus.
Project Structure
A KSoR project is intentionally understandable without proprietary tooling.
KSP-001 defines the structure below, and ksor init emits it — every document in the profile, the generated indexes, and .ksor/governance.yaml beside them. The takedown ledger .ksor/takedowns.yaml is not emitted: the first ksor takedown writes it, because an empty ledger would assert an act nobody performed. docs/status.md remains authoritative for which release carries it.
my-ksor/
│
├── knowledge/ ← authoritative governed record
│ ├── what-is-a-ksor.md ← concept documents: Markdown in the
│ ├── governance-ladder.md KSoR Profile of OKF
│ └── surfaces/
│ ├── for-people.md
│ └── for-agents.md
│
├── .ksor/
│ └── governance.yaml ← audiences, ownership, approval,
│ and takedown authority
│
├── system/
│ └── site/ ← reference human surface (Next.js + Fumadocs)
│
├── .agents/
│ └── skills/ ← agent skills (+ byte-identical .claude/ copies)
│
├── AGENTS.md ← project constitution agents read first
├── instance.md ← what this KSoR is authoritative for
│
└── ...
Under the KSoR Profile of OKF, index.md and log.md are reserved OKF files rather than ordinary concept documents. Publishers generate or manage those files according to the pinned OKF contract instead of using index.md as a normal content page.
knowledge/
The authoritative governed record.
In the KSP-001 architecture, concept documents are Markdown conforming to the KSoR Profile of OKF:
- Markdown is the durable, human-readable medium.
- OKF gives the record an open, portable knowledge structure.
- KSoR governance metadata adds institutional authority: ownership, audience, approval, effectivity, and related controls.
Documents remain:
- portable,
- diffable,
- reviewable,
- version-controlled,
- readable by humans,
- readable by AI coding agents,
- and independent of a proprietary database.
Every concept carries an explicit ksor.audience. Public knowledge says ksor.audience: [public] rather than relying on omission. Stable concepts carry the authority and lifecycle evidence required by KSP-001.
Subdirectories naturally organize the knowledge hierarchy.
.ksor/governance.yaml
The portable Governance Policy for the KSoR instance.
It is the root of authority behind the governance facts carried on individual concepts. KSP-001 defines four governance families:
- the audience registry names non-public audiences,
- the ownership map defines who is accountable for knowledge by scope,
- approval authorities define who may approve knowledge for publication,
- takedown authorities define who may withdraw knowledge.
A simplified policy can look like:
version: "0.1"
audiences:
finance:
description: Finance staff and authorized auditors
ownership:
- scope:
paths: ["finance/"]
types: [Policy, Procedure, Control]
owner: team:finance-controller
escalation: human:cfo@example
approval_authorities:
- scope:
paths: ["finance/"]
types: [Policy, Procedure, Control]
actors: [human:cfo@example]
takedown_authorities:
actors: [human:ciso@example, human:cfo@example]
A conformant publisher validates the corpus against this policy before publication. Governance is therefore mechanically checkable rather than only descriptive.
instance.md
Describes the identity and purpose of this KSoR instance.
For example:
---
format: 2
name: accounting-ksor
title: Accounting KSoR
description: The governed accounting policies, procedures and controls of Example Corporation.
toolchain: { requires: ">=0.1.0", scaffolded: "0.1.0" }
---
Answer only from this record. It is authoritative for accounting
policy, procedure, controls and decision criteria at Example
Corporation, and for nothing else.
name is the machine identity citations and llms.txt use — the one place
an identity is authored rather than derived from a path. title is the
display title every page leads with. The BODY is the MCP server's
instructions, handed verbatim to a connecting agent, so it is written for the
agent rather than as a description of the project.
system/site/
The reference human projection — a real Next.js + Fumadocs app that renders the
record, shipped as ordinary source code you own outright rather than an
opaque hosted service. It is replaceable behind a five-clause surface
contract (specs/ksor/init/spec.md): any shell that renders the record,
degrades directives to readable text, serves llms.txt, passes the browser
smoke, and never emits a document outside the audience it was built for is
equally conformant.
The reference site also exposes machine-readable output such as llms.txt.
That output is another projection of the same governed record, not a separately
maintained AI corpus.
.agents/
Instructions and reusable skills for AI coding agents working on the KSoR.
KSoR is designed to be agent-first.
The agent-maintenance context is not itself authoritative knowledge. It tells coding agents how to work on the authoritative record safely.
Instead of forcing users to manually perform repetitive repository operations, the project can carry the instructions an AI coding agent needs for recurring tasks such as:
- adding knowledge,
- importing source material,
- validating structure,
- creating learning material,
- checking provenance,
- building,
- testing,
- and deployment.
Knowledge as Code
KSoR treats institutional knowledge increasingly like software teams treat source code.
That means knowledge can be:
authored
↓
reviewed
↓
version controlled
↓
validated
↓
tested
↓
built
↓
published
↓
consumed by humans + agents
Git becomes more than storage.
It provides useful primitives for knowledge governance:
- history,
- authorship,
- diffs,
- branches,
- pull requests,
- approvals,
- releases,
- rollback,
- and reproducible builds.
This makes an important shift possible:
Institutional knowledge becomes governed infrastructure.
Build Provenance
Every production answer should be traceable to the knowledge that produced it.
KSoR builds record the exact corpus used to produce a release.
For example:
build.lock.json
can capture information such as:
- included documents,
- document hashes,
- source commit,
- KSoR version,
- build version,
- and other reproducibility metadata.
This creates a chain:
AI Answer
↓
Retrieved Passage
↓
Knowledge Document
↓
KSoR Build
↓
Git Commit
↓
Reviewed Source
When someone asks:
Why did the agent say that?
the architecture should make the answer discoverable.
KSoR binds this responsibility to SLSA and Sigstore: provenance
attestation proving which governed source and build produced a published
artifact. The published @panaversity/ksor package already ships with npm
provenance attached. ksor build writes build.lock.json — the committed
record of which corpus, which commit and which toolchain produced a
publication, stamped into llms.txt, every markdown twin andserver.json — but it signs nothing: SLSA/Sigstore attestation of that lock
is named as out of scope in specs/ksor/build/spec.md §5 and will land
separately.
The Agent Projection
KSoR uses the Model Context Protocol (MCP) as the agent surface: the governed interaction boundary through which agents search, retrieve, cite — and abstain.
llms.txt helps an AI find the knowledge. MCP helps an agent work with it. Moving governed knowledge between systems is OKF's job (KSoR and OKF).
MCP is an interface to the KSoR, not the KSoR itself.
The goal is not to create another model-specific knowledge plugin.
Instead:
KSoR
│
MCP
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
ChatGPT Claude AI Agents
│
┌──────────┼──────────┐
▼ ▼ ▼
Custom Agent Digital
Apps Frameworks FTEs
The knowledge stays independent.
The model or runtime becomes replaceable.
The Machine Projection
AI-native systems increasingly need knowledge in forms that software can consume directly, without scraping a human documentation interface.
A KSoR can therefore expose representations such as:
- canonical governed Markdown,
llms.txt,- structured metadata,
- build manifests,
- indexes,
- and other machine-readable artifacts.
These outputs are derived from the same governed record. They do not become independent sources of truth.
One more machine surface completes the set: governed OKF exchange
bundles — the same representation the record itself is written in,
filtered by governance and packaged for another knowledge system to import.
Because the record is OKF, exchange is selection and packaging, not
translation. (Specified; not yet shipped.)
The durable asset remains the governed knowledge; each representation is replaceable.
KSoR and OKF
The Open Knowledge Format
(OKF) is an
open format for portable knowledge, published by Google Cloud under
Apache-2.0: Markdown documents with YAML frontmatter carrying a trust
vocabulary — sources, verification, freshness, lifecycle — that travels with
the content. OKF is deliberately a format and not a service. Serving,
storage, and query are outside its scope, and its own specification calls its
trust fields "advisory signals, not access control."
KSoR is built on OKF, and therefore uses OKF for interoperability — not
the other way around. The authoritative record is not
converted to OKF at the edge; it is an OKF bundle, constrained by the KSoR
Profile. KSoR invents no knowledge serialization of its own, and exchange
between knowledge systems is governed selection and packaging of the same
native representation — never translation into a proprietary exchange schema.
The division of labor is exact:
- OKF describes knowledge: representation, portable metadata, sources,
verification, freshness, production history. - KSoR makes that knowledge authoritative and operational: ownership,
approval, audiences, takedown, governed retrieval and serving, abstention,
publication integrity, operations.
Or in two lines:
OKF makes KSoR knowledge open, portable, and interoperable.
KSoR governance makes that knowledge institutionally authoritative and operational.
Where OKF ends is where KSoR begins. A format can make knowledge portable; it
cannot make it governed. OKF makes knowledge portable. KSoR makes knowledge
governable.
ksor init emits the KSoR Profile — docs/status.md is the
authority on which release carries it.
KSoR and RAG
RAG answers:
How can relevant information be retrieved and placed into model context?
KSoR answers a broader question:
What knowledge is authoritative enough that an organization permits humans, AI agents, and software to operate from it?
A useful relationship is:
KSoR
│
├── Governance
├── Authority
├── Provenance
├── Versioning
├── Review
├── Scope
├── Human Projection
├── Agent Projection
├── Machine Projection
├── Agent-First Maintenance Context
│
└── Retrieval
├── Search
├── Structured lookup
├── Embeddings
└── RAG
RAG can be part of a KSoR.
A KSoR is not merely a RAG system.
KSoR and a CMS
A Content Management System asks:
How do we create and publish content?
A KSoR asks:
Which knowledge is authoritative, governed, traceable, and safe for humans, agents, and software to rely upon?
Content is an input.
Institutional knowledge is the asset.
Authority is the differentiator.
Governance Model
A KSoR must govern both sides of authority:
- the write side determines how knowledge becomes authoritative,
- the read side determines whether that knowledge may cross a serving or publication boundary.
KSP-001 defines the write-side lifecycle this way:
source material
│
▼
draft authored by a human or agent
│
▼
review under the authority of the named owner
│
▼
approval granted by an authorized actor and recorded in change control
│
▼
stable authoritative knowledge that may be served
│
├── change re-approve in the same reviewed change,
│ or return to draft
│
├── deprecated under owner or takedown authority
│
└── takedown governed withdrawal, then removal from every current surface
Approval is an authority event. stable is the lifecycle state. They are deliberately separate. A concept does not become authoritative merely because someone changed its status text.
Imported knowledge enters as candidate knowledge at draft. External trust signals can be preserved as evidence, but they do not become local approval.
The Governance Policy in .ksor/governance.yaml defines the audience registry, ownership rules, approval authorities, and takedown authority used to validate these events.
For regulated or high-risk knowledge, organizations can add controls appropriate to their domain, including:
- named knowledge owners,
- approval requirements,
- effective dates,
- source citations,
- mandatory review periods,
- change records,
- conflict resolution,
- separation of duties,
- and audit history.
The organization remains responsible for its governance policy. KSoR makes that policy explicit, portable, and enforceable across every surface.
Knowledge Boundaries
A trustworthy KSoR has a boundary.
The existence of an AI model does not remove that boundary.
Consider three questions:
In scope
What approval threshold applies to purchases over $50,000?
If an approved purchasing policy answers the question, KSoR should provide the answer and source.
Requires reasoning
Does this particular purchase require CFO approval?
The system may need to combine the governed rule with operational facts from another System of Record.
Outside the KSoR
What approval policy will the company adopt next year?
If that information has not been approved and entered into the KSoR, the system should decline rather than speculate.
This distinction is essential for trustworthy agentic systems.
KSoR in an AI-Native Architecture
An AI-native organization cannot rely on model memory, scattered documents, or an ungoverned RAG index as its institutional knowledge layer.
KSoR becomes especially important when AI agents begin performing real organizational work because it gives humans, agents, and software a shared, governed basis for interpretation and action.
Human / AI Worker
│
▼
Agent
│
┌────────────┴────────────┐
│ │
▼ ▼
KSoR Operational SoRs
│ │
Knowledge Current State
│ │
Policies / Methods CRM / ERP / HRIS
Rules / Procedures Ledger / Database
Standards / Specs Orders / Inventory
│ │
└────────────┬────────────┘
│
▼
Decision
│
▼
Action
The KSoR tells the agent how the organization operates.
Traditional Systems of Record tell the agent what is currently true.
Together they provide the context required for reliable enterprise action.
Agent-First Development
KSoR is designed for a development world in which coding agents perform much of the mechanical work.
A scaffolded KSoR can carry machine-readable instructions for tasks such as:
"Add this policy to the KSoR."
"Convert these source documents into governed Markdown."
"Check every page for missing provenance."
"Build a quiz from this section."
"Validate the KSoR."
"Run the test suite."
"Prepare this release."
"Deploy the human surface."
The repository therefore becomes both:
- the knowledge artifact, and
- the working context for the agents that maintain it.
This allows subject-matter experts and software engineers to collaborate around the same governed source.
Human-Readable by Default
KSoR does not require organizational knowledge to disappear into a vector database.
The canonical source remains inspectable.
A person should be able to:
- open it,
- read it,
- diff it,
- review it,
- copy it,
- migrate it,
- and understand what the AI is being allowed to use.
This is an intentional architectural property.
Vendor-Neutral by Design
Your KSoR should survive changes in:
- LLM providers,
- embedding models,
- vector stores,
- agent frameworks,
- cloud providers,
- AI applications,
- and user interfaces.
The durable asset is the governed knowledge.
Everything around it should be replaceable.
Deployment
The human surface generated by pnpm build in a scaffolded project is a fully
static site. pnpm build is two steps: ksor build checks the record and
writes build.lock.json, then the site build stages what this viewer may see
and exports it. ksor build never renders the site itself — it is
database-free and knows nothing about a shell.
That makes it suitable for hosts such as:
- Vercel,
- Netlify,
- GitHub Pages,
- static object storage,
- internal web servers,
- nginx,
- and private infrastructure.
Hosting under a sub-path (like user.github.io/repo) is the one build-time
setting: KSOR_BASE_PATH=/repo pnpm build.
Detailed deployment guidance can live with each generated project so the instructions remain version-aligned with the KSoR release being used.
Working Behind the Firewall
A Knowledge System of Record frequently contains internal organizational knowledge.
KSoR therefore aims to support architectures in which:
- the knowledge remains under organizational control,
- the website can be self-hosted,
- external runtime dependencies are minimized,
- and the agent interface can be deployed inside the organization's security boundary.
A KSoR should not require an organization to publish its institutional knowledge to a third-party SaaS platform simply to make it usable by AI.
Example Applications
Agent Factory KSoR
Agent Factory illustrates the transition KSoR is designed to support: from a human-readable book plus retrieval service toward an AI-native knowledge platform where humans and AI agents learn, reason, and operate from the same governed source of truth.
The Agent Factory KSoR can define the shared methodology used across many AI-native implementations:
Agent Factory KSoR
├── architecture
├── principles
├── FDE methodology
├── governance
├── agent patterns
├── evaluation standards
├── implementation methods
└── operating model
It acts as a shared methodological System of Record.
Vertical KSoR
A Vertical KSoR captures knowledge specific to a profession or industry.
For example:
Government Contract Accounting KSoR
├── accounting rules
├── FAR requirements
├── contract structures
├── indirect rates
├── revenue recognition
├── billing procedures
├── compliance controls
├── workflows
└── decision criteria
Agents can combine the Agent Factory KSoR with the appropriate Vertical KSoR when performing domain work.
Agent Factory KSoR
Shared Method
│
│
▼
AI Agent
▲
│
│
Vertical KSoR
Domain Truth
Both can be built using the same ksor SDK.
What KSoR Does Not Replace
KSoR is complementary to existing enterprise systems.
It does not replace:
- your CRM,
- ERP,
- accounting system,
- HRIS,
- transactional database,
- data warehouse,
- lakehouse,
- document source systems,
- or operational APIs.
Those systems remain authoritative for their respective operational state.
KSoR adds the authoritative knowledge layer agents need in order to understand how to interpret that state and what to do with it.
Design Goals
KSoR is being designed around the following goals.
Authoritative
There should be a clear canonical source.
Governed
Knowledge should have ownership and controlled change.
Traceable
Important answers should lead back to evidence.
Inspectable
Humans must be able to see what agents are reading.
Portable
Knowledge should not be trapped inside one vendor. An open format under the
record (OKF) and open protocols over it are how.
Agent-readable
AI agents must be able to consume the corpus programmatically.
Human-readable
People must be able to browse and understand the same knowledge.
Versioned
Changes to institutional truth should have history.
Reproducible
A deployed KSoR should be traceable to a particular corpus and version.
Composable
Multiple KSoRs should be usable together — and exchange governed knowledge in
the same open representation, without a proprietary conversion.
Extensible
Organizations should be able to adapt the framework to their requirements.
Project Status
KSoR is under active development.
The MCP-based agent projection (ksor serve) is implemented — the climbed rung,
needing Postgres and a provider key; see docs/status.md for
the released version.
See:
CHANGELOG.md— what has shippeddocs/status.md— current implementation statusCONTRIBUTING.md— contributingSECURITY.md— security policy
Do not infer production readiness of a capability from this conceptual README alone. The status document and released package version are authoritative for implemented functionality.
CLI
The intended CLI vocabulary is deliberately small:
ksor init
ksor dev
ksor build
ksor migrate
ksor serve
# corpus operations for the served rung:
ksor ingest
ksor schema
ksor grant
ksor takedown
ksor calibrate
ksor gc
ksor init — implemented
Create a new Knowledge System of Record.
ksor init accounting-ksor
ksor dev
Run the human surface locally with development tooling.
ksor dev
ksor build — implemented
Generate every knowledge/**/index.md in memory, check the whole record, and —
only if it passes — write the indexes whose bytes changed plusbuild.lock.json. It needs no database, no provider key and no network. A
refusal exits 1 with the slug on the first stderr line and writes nothing, so
a red build leaves the tree as it found it.
ksor build
ksor build --as-of 2026-09-01T00:00:00Z # pin the instant lifecycle is judged at
--bundles, which would write one OKF bundle per registered audience for
exchange, is designed and exits 2.
ksor migrate — implemented
Rewrite a record written before the KSoR Profile into it: audiences expanded
upward from the old ordered model, provenance into sources, the instance into
format 2, authority into .ksor/governance.yaml. It prints a unified diff and
changes nothing until --write, and refuses by name rather than invent a title,
a description or the actor behind a takedown.
ksor migrate --actor human:you # prints the diff, writes nothing
ksor migrate --write --actor human:you --approve-by human:you
--approve-by is not optional decoration. Without it every approved
document becomes a draft, and a draft reaches no machine surface: the
following ksor build reports 0 admitted to a machine surface and the
record's llms.txt, /md/ twins and MCP door publish nothing until a human
approves. Where one document supersedes another, ksor build refuses outright
with ksor-supersession-strands — the successor migrate just demoted is a
draft, and a reader sent to it would be stranded. Pass it when you are the
person .ksor/governance.yaml authorises to approve; otherwise plan to
approve the record document by document before it publishes again.
ksor serve — implemented (the climbed rung)
Expose the agent-readable KSoR interface: the MCP server over your built record,
reading ./instance.md. Needs a Postgres store (pgvector) and an embedding
provider key; ingest with ksor ingest first.
ksor serve
ksor ingest / schema / grant / takedown / calibrate / gc — implemented
The corpus operations behind the served rung: apply the schema (or migrate an
existing one forward), authorize a tenant to ingest, ingest knowledge/ into a
generation, withdraw a document from every surface, calibrate the abstention
floor, and collect withdrawn generations. All but takedown need the same
Postgres store: a takedown is written to the committed ledger.ksor/takedowns.yaml first and to the denylist row second, so a record with
no database can withdraw a document, and the site reads the withdrawal from the
repository rather than from an exported manifest.
grant is the one to read twice: who may WRITE a tenant's corpus is decided by
a row in the database that row-level security checks, never by a flag on a
command line.
The npm package is@panaversity/ksor — the
unscoped name ksor is blocked by npm's similarity guard — but the command it
installs is plain ksor.
The installed release's help lists the commands it supports:
ksor --help
Contributing
Contributions are welcome.
Before contributing, read:
AGENTS.md
docs/status.md
CONTRIBUTING.md
The project is intentionally agent-friendly, so coding agents should also read AGENTS.md before making changes.
The development gate is defined in CONTRIBUTING.md:
lint, format check, typecheck, guard invariants, corpus checks, unit and
integration tests, build, and publint. Browser and deployment acceptance will
join it when a site surface exists.
Do not weaken provenance, abstention, governance, or reproducibility guarantees merely to simplify an implementation.
Those are part of the product.
Security
Knowledge Systems of Record can contain sensitive institutional information and can influence AI agent behavior.
Treat security issues involving the following as particularly important:
- unauthorized corpus access,
- provenance bypass,
- malicious source ingestion,
- prompt injection through knowledge content,
- privilege escalation,
- unsafe MCP exposure,
- build tampering,
- dependency compromise,
- and the ability to make ungoverned knowledge appear authoritative.
See SECURITY.md for reporting instructions.
License
KSoR is licensed under the Apache License 2.0.
The Idea in One Sentence
A traditional System of Record tells an AI system what is true about the organization; a Knowledge System of Record tells humans and AI what the organization knows and how they are allowed to operate.
You cannot build predictable AI systems on an undefined source of truth.
For enterprises, KSoR gives agents one governed institutional truth. For education, it gives teaching agents one governed academic truth. The AI may reason, adapt, and personalize, but it does not get to invent which knowledge is authoritative.
KSoR
Govern knowledge once. Let humans and AI operate from the same truth.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi