AgenticSystemCore README

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

Released. This tree states specification 1.0.0. 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 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 agentic-system-core. The reference engine claims Level 3 (its claim).

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.

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 (, ).

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                                   # 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 (the marketplace file .claude-plugin/marketplace.json points at the plugin in plugins/).

Who it is for, what you get, try it

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.

Reference engine

The reference implementation of the specification lives in this repository, under src/. It claims Level 3, the full engine. 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); the engine's claim is kept in docs/CONFORMANCE-STATEMENTS.md, with what each part of it rests on, and reads:

agentic-system-core 1.0.0 conforms to AgenticSystemCore 1.0.0, Level 3. Verified against the published conformance vectors on 2026-10-12: 243 of 243 passed in the 20 populated areas (adopt, boards, boundary, build, bundle, chunks, cli, compose, conform, discovery, export, frontmatter, graph, import, jcs, ledger, links, lint, prov, slug), 242 required and 1 optional, the 7 withdrawn cases excluded, with Unicode 17.0. Deployment profile: cloudflare-pages — the reference profile: _headers and _redirects as agsc build writes them. Surfaces: llms-txt (proved by disc-0013, disc-0014), chunks (proved by chk-0001, chk-0002, chk-0003, chk-0004, chk-0005, chk-0006, chk-0008), webmcp (proved by cli-0003).

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 a release candidate. CHANGELOG.md has one section for each step: Upgrading from 1.0.0-rc.7, under 1.0.0, and Upgrading from 1.0.0-rc.6, under 1.0.0-rc.7. Each says what a node built with the earlier version may now see refused, what changes in the built files, and what to do. A node still on 1.0.0-rc.6 reads the second section first, then the first.

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 twenty-one 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 the package tag, v1.0.0 (not the specification tag 1.0.0), or to that tag's 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@v1.0.0

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. Pin rev the same way, to the package tag or its full commit SHA. The hook runs under the system Node, which must be Node 22.13 or later; where the system Node is older, set language_version for the hook to a newer version:

repos:
  - repo: https://github.com/andreibesleaga/agentic-system-core
    rev: v1.0.0
    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 and contains no model adapter. The model steps the specification describes are optional: a live run is made by an agent outside the engine — Claude Code, a script — as a client of agsc mcp or the page tools, under the lane's declared limits (AGSC-08-28), and it is the responsibility of the person who runs that agent. 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

Outside 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.