Read, cite, compose and remember over a Markdown knowledge Bundle, as MCP tools over stdio.
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).
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.
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.
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).
For agents
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).For people
From a clone of this repository (Node 22.13 or later):
npm ci # the exact pinned libraries
npm test # the whole suite, offline
REPO=$PWD; cp -r tests/fixtures/minimal /tmp/agsc-try && cd /tmp/agsc-try
SOURCE_DATE_EPOCH=1767225600 node "$REPO/bin/agsc.js" ci # lint, build twice, compare, verify: "ci: pass"
On a folder of your own Markdown notes (Node 22.13 or later, git, a POSIX shell):
npm install agentic-system-core # in a working folder
export PATH="$PWD/node_modules/.bin:$PATH" # puts agsc on the PATH
cd my-notes && agsc init # each note gets a header and moves to content/concepts/
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' # the build takes its instant from this commit
agsc ci # ci: pass (warnings are advice, errors stop)
agsc build # the site, the graph and the agent files in www/
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.
| 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 |
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.
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 |
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.
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
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.
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.
AgenticSystemCore™ is a trademark of Andrei N. Besleaga. Other names belong to their owners.
| 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.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y agentic-system-coreMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-andreibesleaga-agentic-system-core": {
"command": "npx",
"args": [
"-y",
"agentic-system-core"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceAgenticSystemCore works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.