Agentic System Core
A specification for publishing machine-discoverable knowledge bundles — the Agentic Knowledge Web.
What this repository holds is the specification itself — numbered normative rules, three JSON Schemas, an OWL 2 RL ontology and a suite of conformance test vectors — together with the reference engine that implements it, its command line agsc, and the nine independent checkers of AGSC-09-90 — seven validators and two generators — that anyone can run against any distribution of the format (the repository also holds the maintainer's own tools, which do not ship).
Status
Release candidate. This tree states specification 1.0.0-rc.7, the second public release candidate (the first was 1.0.0-rc.6). spec/00-overview.md is authoritative, and it is the file to read rather than this line. The packages — agentic-system-core and its short alias agsc-cli on npm, and agentic-system-core on PyPI — carry version 1.0.0-rc.7 and are published from the release tag; the name-reservation placeholders that preceded them shipped no runtime and are marked deprecated on npm and yanked on PyPI. Install with npm install agentic-system-core, or pip install --pre agentic-system-core (pip installs a release candidate only when asked with --pre).
The specification's own site is AgenticSystemCore.com.
In three sentences
A Bundle is a folder of Markdown files with a small block of typed fields at the
top of each; the specification says how that folder becomes a knowledge node — a
static website plus a graph, a search index, text files for agents and a discovery
document — with the same bytes from any implementation. People and agents read a node
through ordinary web addresses, change it only by proposals that a person ratifies, and
compose its items into a starting harness — files an architect or an agent runtime
starts from. Nodes find and cite each other with no server in between.
What is different about it
To the author's knowledge, no other system combines discovery through already-registered web
mechanisms with an integrity digest on every artefact link of its discovery document, a typed graph with a
published ontology, machine artefacts whose bytes are fixed by expected-byte
conformance vectors, governance in which every change — human or agent — arrives as a
proposal carrying its provenance and a person ratifies it (directly, or by a standing
rule a person recorded in the node's configuration), and composition of the same files
into a starting harness, with no server required at any point.
This is a claim about the specification's text and its vectors, not a performance
claim. Other systems have some of these properties; the dated comparison is in
docs/RELATED-WORK.md.
| Property | What it means | Where it is stated and proved |
|---|
| Discovery through registered mechanisms | one link set at a well-known address, found through the registered relation describedby | AGSC-06-07, AGSC-06-25; tools/validate-wellknown |
| A digest on every artefact link | at Level 2, each link of the discovery document to a file the node builds (the graph files, llms.txt, NOW, the skills and boards indexes, the ledger, the vocabulary files) carries the SHA-256 of that file; links to surfaces, the licence page, peers and contribution targets carry none | AGSC-06-08; the discovery vectors |
| A typed graph with an ontology | fourteen typed links, four RDF views, a published OWL 2 RL vocabulary | spec/05-graph.md, ontology/agsc.ttl |
| Bytes fixed by vectors | two implementations given one Bundle emit the same machine files | AGSC-04-24; tests/vectors/ |
| Governance with provenance | every change is a proposal with its provenance; a person ratifies; a ledger is derived from the history | spec/08-governance.md (AGSC-08-08, AGSC-08-20) |
| Composition into a harness | selected items close over their links and become seven kinds of file an architect or an agent runtime can start from | AGSC-07-12; agsc compose |
| No server | a file format and static files; no protocol, server, database or reasoner is defined | AGSC-00-02 |
Beside that combination, and each available elsewhere on its own: six modes of use
(docs/plain/modes.md); seven tools on every item page and on /compose/ for a
browser's own agent, identical to the local tool server (AGSC-09-16);
eight plugin kinds with a forward-compatibility promise (docs/PLUGINS.md,
AGSC-00-24); a content version stamped on every surface
(AGSC-04-25); and federation walked by the client,
never by a node (AGSC-11-06).
What it is best for
For agents
- Memory for one agent.
agsc mcp in a Bundle gives an assistant seven tools to
search, read, follow links and cite items by address; nothing leaves the machine
(Mode 1, use case L1).
- Shared memory for many agents. Every agent reads the same published files and
writes only by proposals a person ratifies
(Mode 1, docs/CONNECTORS.md).
- A source of skills. Each cluster becomes one skill pack holding its published
items — the procedures are the part an agent follows — with a lockfile of their
digests, installable into agent tool folders; skills from other repositories come
in as procedures
(Mode 3, use case L4).
- A starting harness. A selection of items becomes a harness — seven kinds of file
an architect or a runtime can start from; it is not a running system, and no
rendering for a particular runtime ships at 1.0 (Mode 4, use case M5).
- A live board for a team of agents. Agents claim and finish tasks on shared boards
until they are done; decisions stay with people
(Mode 5, use case M1).
- Knowledge across nodes. A client reads several nodes' graph dumps and joins them
locally, every foreign result marked with its origin; at 1.0 the walk is a library
function of the engine, not a command
(Mode 1, use case D4).
For people
- A wiki that corrects itself. Markdown in, a checked and linked site out, with
every change reviewed (Mode 0, use case L5).
- A project's living specifications. Decisions, specifications, tasks and gates
as one governed memory, and steering files that keep a coding agent on course
(Mode 2, use case L3).
- A library of patterns. Concepts with sources and provenance, readable without
JavaScript, composable into a starting architecture
(Mode 4, docs/USE-CASES.md).
- A team board. A board from GitHub, GitLab, Jira, Trello, Linear, Asana, Notion,
Obsidian or plain Markdown becomes a live board and goes back again
(Mode 5, use case M7).
Quick start
From a clone of this repository (Node 22.13 or later):
npm ci
npm test
REPO=$PWD; cp -r tests/fixtures/minimal /tmp/agsc-try && cd /tmp/agsc-try
SOURCE_DATE_EPOCH=1767225600 node "$REPO/bin/agsc.js" ci
On a folder of your own Markdown notes (Node 22.13 or later, git, a POSIX shell):
npm install agentic-system-core
export PATH="$PWD/node_modules/.bin:$PATH"
cd my-notes && agsc init
mkdir -p .well-known && printf 'Contact: mailto:you@example.org\n' > .well-known/security.txt
git init -q && git add -A && git commit -q -m 'my notes'
agsc ci
agsc build
Without the security contact ci stops with AGSC-E901; without a commit (or
SOURCE_DATE_EPOCH) it stops with AGSC-E204. The
Mode 0 guide
walks through this with the lines each command prints, and five more
guides
do the same for the other modes. To connect an assistant, read
docs/USING-WITH-ASSISTANTS.md.
To teach a coding agent the engine itself, install the agent skill in
skills/agentic-system-core/: npx skills add andreibesleaga/agentic-system-core,
or in Claude Code claude plugin marketplace add andreibesleaga/agentic-system-core.
Who it is for, what you get, try it
| Reader | What you get today | Try it |
|---|
| A person with a folder of notes | a static site of your notes with search, each page also as Markdown, a graph file and text files for assistants; no model, no server | the quick start above; the Mode 0 guide |
| A developer | a local tool server: seven tools over your folder for an assistant; nothing leaves the machine | agsc mcp, set up as in docs/USING-WITH-ASSISTANTS.md; the Mode 1 guide |
| A team running an agent-assisted development process | decisions, specifications, tasks and gates as checked files; one steering file with the same bytes for every coding assistant; a gate compiled to one required CI check | the Mode 2 guide; agsc ci, agsc export --steer |
| An architect | a selection of items checked against their typed links and written as seven kinds of file (agent instructions, a C4 model, a diagram, an arc42 skeleton, decision records, skill files): a starting point, not a running system | the Mode 4 guide; agsc compose <slug>… --zip, or the /compose/ page of a live node |
| An engineer implementing or checking the format | test cases with expected bytes; checkers that judge any implementation's files; a second checker in Python | agsc conform --level 3; node node_modules/agentic-system-core/tools/validate-wellknown https://agenticsystemcore.com/.well-known/knowledge-linkset --level 2; docs/IMPLEMENTERS-GUIDE.md |
| A manager deciding whether to depend on it | what you can rely on (open licences, permanent addresses, archived releases, checks by published bytes) and what you cannot (one maintainer, no support promise, no schedule); the state of every outside step; the security policy | read GOVERNANCE.md, SECURITY.md and the status page; look at a live node: https://patterns.agenticsystemcore.com/ |
| An agent or its operator reading a node | one discovery document that lists every machine file with its digest; text files, chunks and graph files at fixed addresses | curl -s https://agenticsystemcore.com/.well-known/knowledge-linkset, then the checker line above |
Where to start reading
docs/START-HERE.md sends each kind of reader — someone curious,
a person with notes, a developer, a team with coding assistants, an implementer in
another language, an architect, a manager, an agent, a standards reviewer or a
maintainer — down one path. Agents and coding assistants working in this
repository read AGENTS.md first.
Documentation map
The official repository is https://github.com/andreibesleaga/agentic-system-core; the site is https://agenticsystemcore.com.
| Topic | Read |
|---|
| The specification (the standard itself: 343 rule ids, 332 of them active, in twelve chapters) | spec/ — start with spec/00-overview.md; a plain-language edition is in docs/plain/ |
| How to read the specification | docs/SPEC-ORIENTATION.md, docs/SPEC.md |
| The protocol: discovery document, link set, digests, peers, tool surfaces | docs/PROTOCOLS.md, spec/06-surfaces.md, spec/11-boundary.md |
| The Internet-Draft (the well-known link set; an individual Internet-Draft) | internet-draft/ |
| Schemas and vocabulary (JSON Schemas, OWL 2 RL ontology, JSON-LD context) | schema/, ontology/ |
| Architecture | docs/ARCHITECTURE-GUIDE.md, docs/ARCHITECTURE-DDD.md, docs/diagrams/ |
| Standards it builds on and related work | docs/RELATED-WORK.md, docs/COMPLIANCE-CROSSWALK.md |
| Conformance: Levels, vectors, how to state a claim | spec/09-conformance.md, spec/10-implementation-profiles.md, tests/vectors/, docs/CONFORMANCE-STATEMENTS.md |
| Implementing it in another language | docs/IMPLEMENTERS-GUIDE.md |
| Using it: modes, guides, demos, connectors, assistants | docs/plain/modes.md, docs/guides/, docs/DEMOS.md, docs/CONNECTORS.md, docs/USING-WITH-ASSISTANTS.md |
| Plugins and extension points | docs/PLUGINS.md |
| Security and threat model | docs/SECURITY-CONSIDERATIONS.md, SECURITY.md |
| Engineering, testing, measurements | docs/ENGINEERING.md, docs/TESTING.md, docs/MEASUREMENTS.md, docs/BENCHMARKS.md |
| Requirements and use cases | docs/PRD.md, docs/USE-CASES.md, docs/REQUIREMENTS-MATRIX.md |
| What comes next | docs/ROADMAP.md |
| Governance, trademark, contributing, licences | GOVERNANCE.md, TRADEMARK-POLICY.md, CONTRIBUTING.md, NOTICE |
| Glossary and the full docs index | docs/GLOSSARY.md, docs/README.md |
Reference engine
The reference implementation of the specification lives in this repository,
under src/. It claims no conformance Level yet: a claim of any Level exists
only after a green run of that Level's vector set and is published in the form
of AGSC-09-01 (AGSC-10-05). All sixteen
verbs of AGSC-09-07 are implemented; run and trace are off by default, as
AGSC-09-94 requires. agsc init adopts a folder of Markdown; before the first
build the publisher adds .well-known/security.txt with a Contact: line (RFC
9116) and commits once or sets SOURCE_DATE_EPOCH, as init says on its way out;
agsc ci checks, and agsc build writes the site.
src/README.md is the engine's own documentation — the bounded contexts, the
module map, the verb → module table, how to run the conformance vectors, and
the list of specification items this work found and reported rather than
worked around.tests/vectors/** is the acceptance test, and it is the part that matters to
anyone implementing this format in another language: a port needs spec/,
schema/, ontology/ and those vectors, and nothing from src/.npm test runs the whole suite, and the conformance runner prints one summary
line.docs/PLUGINS.md is the plugin contract: the eight kinds this format admits
(AGSC-00-24), what a plugin of each may read, emit and never do, how the engine
finds one, and what is promised not to break within 1.x. examples/plugins/
holds one minimal sample per kind; at 1.0 a command loads three of the kinds (a
memory adapter, a composition emitter and a deployment profile), and the other
five samples are proved by the plugin-contract test only.
The engine's arrangement is one implementation choice, not part of the format.
Where this engine and the specification disagree, the specification wins.
What the package promises to keep within 1.x. The command line — the
commands agsc, agsc-host and agentic-system-core, their verbs, flags, exit
codes and output envelopes (AGSC-09-07 to AGSC-09-12) — the plugin contract of
docs/PLUGINS.md (plugin API 1.0.0), the nine checkers run as programs
(node tools/<name>), and the six names require('agentic-system-core') returns:
LINK_RELATION, PROFILE_URI, WELLKNOWN_SUFFIX, run, specVersion and
version. package.json declares no exports map, so every file under src/,
bin/ and tools/ can still be required; none of them is part of the promise,
and their names and signatures may change in any release. The one exception is
run() of bin/agsc.js, the entry the agsc-cli alias package calls.
Upgrading from 1.0.0-rc.6. CHANGELOG.md has a section of that name: what a
node built with rc.6 may now see refused, what changes in the built files, and
what to do.
Connecting agents and repositories
docs/CONNECTORS.md says, route by route, how an agent or a framework uses a
published Bundle — steering files, skill packs, the MCP server, and the COGX
memory archive (agsc export --to cogx / agsc import --from cogx), the format Cognee
reads and writes and into which it translates Mem0, LangMem, Letta and Zep memories
when they are migrated into Cognee. examples/connectors/ holds the
working examples, and docs/USE-CASES.md walks through nineteen concrete scenarios
with their commands.
Check a Bundle on every push (GitHub Actions). action.yml at the root of this
repository is a composite action that runs agsc ci with the engine at the same
commit as the action, so the ref you write pins the engine version. Pin it to a
release tag or a full commit SHA, give the job read access only, and fetch the
history the ledger reads:
permissions:
contents: read
jobs:
agsc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@<commit-sha>
with:
fetch-depth: 0
- uses: andreibesleaga/agentic-system-core@<tag-or-commit-sha>
Lint before every commit (pre-commit). .pre-commit-hooks.yaml offers one hook,
agsc-lint, which runs agsc lint over the whole Bundle whenever an item or the
configuration changed:
repos:
- repo: https://github.com/andreibesleaga/agentic-system-core
rev: <tag-or-commit-sha>
hooks:
- id: agsc-lint
How this is made
This work is written and maintained by Andrei N. Besleaga with the help of AI
assistants. A person decides what is written, an assistant drafts and checks it, and a
person reads, edits and approves everything that is published and answers for it. Every
published item records how its text was made and names the person accountable for it.
Written with AI assistance, reviewed and published by a person.
The assistance covered text, code, figures and diagrams alike. The engine itself calls no
AI model: it contains no model adapter, and the model steps the specification describes are
optional, off unless the person running an engine adds an adapter of their own and turns
them on, and that person's responsibility. What an assistant or agent writes from this
work is its own output, not a statement by the author.
What this does not claim
This is the independent work of one person, published as it is, with no warranty of any
kind and no liability for anything that follows from using it. Nothing in it is legal or
professional advice. No standards body, foundation, company or institution named in this
repository has reviewed, approved or is connected with this work, and it is not a document
of the IETF, of the W3C or of any other body. Other product and organisation names are the
marks of their owners and are used only to say what is being talked about.
Every right not expressly granted by the licences is reserved, and nothing here promises
that the work or its addresses will stay available.
Notice
AgenticSystemCore™ is a trademark of Andrei N. Besleaga. Other names belong to their owners.
Licences
| What | Licence |
|---|
| The engine, the command line and the checkers | Apache-2.0 (LICENSE) |
| The JSON Schemas, the ontology, the identifiers and the discovery document | CC0-1.0 |
The specification text under spec/ | Apache-2.0 |
The conformance vectors under tests/vectors/ | Apache-2.0 |
| The prose of a published node — item bodies, descriptions and the pages and exports that carry them | the Content Use Terms in LICENSE-CONTENT |
Contributions are signed off under the agreement in CONTRIBUTOR-AGREEMENT, which the
token CA-v1 names; CONTRIBUTING.md says what that means in plain words.
GOVERNANCE.md says who decides and what happens if the maintainer stops,
TRADEMARK-POLICY.md how the project's name may be used,
docs/CONFORMANCE-STATEMENTS.md how to say that an implementation conforms,
CODE_OF_CONDUCT.md how people are expected to behave, and SECURITY.md how to
report a vulnerability privately.
© 2026 Andrei N. Besleaga. Code: Apache-2.0. Schemas, ontology, identifiers and the
discovery document: CC0-1.0. Prose: the Content Use Terms in LICENSE-CONTENT.