Knosis

Knosis = knowledge + gnosis. A knowledge substrate for agents: collect, manage and reuse what your agents learn.

English | 中文

Live demo: https://eason-nuosen.github.io/Knosis/

Knosis is not an agent. It lets coding agents such as Codex and Claude Code write down what they learn while working as explicit knowledge: every piece of knowledge has a source, the conditions under which it holds, and evidence, so it can be checked, traced and retracted; the next time the agent works, it retrieves what it needs.

Two scenarios, one knowledge layer:

• Personal agents: collect knowledge from your everyday Codex / Claude Code sessions into a personal knowledge base; new sessions use it through MCP.
• Tasks and enterprise data: on concrete tasks (benchmarks, business data) the agent accumulates knowledge as it explores; knowledge verified by evidence is written back to the knowledge base and can be inherited by similar tasks.

Core concepts

• Knowledge unit κ: one piece of knowledge = content, form (fact / rule / formula / procedure ...), conditions, source and status (observed → inferred → verified, or contested / retracted / stale / merged). Stored in kb/knowledge/units.jsonl.
• Evidence: records that support or refute a unit (executable checks, tool output, dev feedback, trace steps), stored in evidence/. A unit's status must agree with its evidence.
• Consolidation: as knowledge grows, the agent deduplicates it, resolves contradictions, organizes it into a knowledge system (outline, knowledge graph, flows), and compacts it when it gets too large. Knosis checks every step, rolls back steps that fail, and logs what was done.
• Workspace: the full pipeline for one task, explore → extract → refine (corrected with dev feedback) → decide. Each stage is checked and committed to git; ground truth never enters the workspace.

Knowledge bases and workspaces share the same layout (kb/ + evidence/). Both are local git repositories with one commit per write-back, so every version can be restored.

Installation

pip install knosis               # Python 3.10+
pip install 'knosis[all]'        # plus the dependencies some datasets need (networkx, h5py, openpyxl, downloaders)

You also need a coding agent: Codex CLI or Claude Code; both are tested. From source: git clone, then pip install -e '.[all]'; run the tests with pytest -q.

Prompts, task briefs and data cards given to the agent are in English, so the agent writes knowledge in English. Set KNOSIS_LANG=zh to use the Chinese versions (knosis/workspace/templates_cn/, knosis/data/cards_cn/) instead.

Quick start: personal knowledge base

No dataset required.

knosis kb init ~/kb                                  # create the knowledge base (a local git repository)
knosis install --kb ~/kb                             # let Codex / Claude Code use it, see the next section

# work with your agent as usual; in a new session it first reads the outline, then searches for the task at hand

knosis kb collect --kb ~/kb --since 1d --dry-run     # see which sessions would be collected
knosis kb collect --kb ~/kb --since 1d               # extract → check → consolidate → commit a version (--source claude for Claude Code sessions)

knosis knowledge outline --ws ~/kb                   # the knowledge system
knosis knowledge select  --ws ~/kb --text <keyword>  # search
knosis knowledge trace <id> --ws ~/kb                # where a unit came from and its evidence

Only knowledge the environment can confirm or refute is collected (project conventions, data pitfalls, how tools and commands actually behave, errors and their fixes, reusable methods), not preferences or chat. Session transcripts are copied into the knowledge base for traceability, so do not push your knowledge base to a public remote.

Using Knosis from Codex and Claude Code

Knosis connects to agents through two things: a skill (tells the agent the knowledge base exists, when to consult it and how to write back) and an MCP server (knosis mcp, 16 tools to query and write knowledge inside a session). knosis install --kb ~/kb installs both:

In a new session the agent first reads the outline (knowledge_outline), then searches for the task (knowledge_select). You can also just ask it to "look up what the knowledge base says about X" or "record this finding in the knowledge base".

Collection does not happen inside sessions; run it periodically (e.g. from cron):

knosis kb collect --kb ~/kb --since 1d                                  # Codex sessions (~/.codex/sessions)
knosis kb collect --kb ~/kb --since 1d --source claude                  # Claude Code sessions (~/.claude/projects)
knosis kb collect --kb ~/kb --since 1d --agent claude --model <model>   # use Claude Code for extraction (default: Codex)

Try the MCP server without a global install:

codex exec -c 'mcp_servers.knosis.command="knosis"' -c 'mcp_servers.knosis.args=["mcp","--ws","/abs/path/kb"]' \
  -c 'mcp_servers.knosis.default_tools_approval_mode="approve"' "<task>"
claude -p "<task>" --mcp-config '{"mcpServers":{"knosis":{"command":"knosis","args":["mcp","--ws","/abs/path/kb"]}}}' \
  --allowedTools mcp__knosis

Every command that runs an agent (ws run, kb collect, knowledge consolidate / compact) takes --agent codex|claude, --model and --effort.

Quick start: task workspace

knosis ws init tabarena houses --out ws/houses       # export a workspace from a dataset (data entries below)

# driver mode: Knosis runs the agent through every stage, checks each one and retries once on failure
knosis ws run ws/houses --agent codex --stage explore extract refine decide --rounds 2 --consolidate
knosis ws run ws/houses --agent claude --model <model> --effort medium ...   # with Claude Code

# embedded mode: open the workspace in your agent (Codex reads AGENTS.md, Claude Code reads CLAUDE.md) and let it proceed
knosis install

knosis eval ws/houses                                # evaluate, writes .knosis/eval.json
knosis ws fork ws/houses --out ws/houses-none --knowledge none   # ablation: no knowledge / K_0 / K_final

Ground truth is only read at evaluation time, test tasks are generated only at decide, and feedback only accepts dev tasks. This is soft isolation, not a security boundary: for formal evaluations keep the raw data outside the agent's environment.

Managing knowledge

knosis knowledge check       --ws <dir>                    # structure, sources, status vs. evidence
knosis knowledge consolidate --ws <dir>                    # deduplicate → resolve contradictions → organize → structure
knosis knowledge compact     --ws <dir> [--topic <topic>]  # shrink a large base: agent decides what to merge, or only one topic
knosis knowledge view        --ws <dir>                    # browse the knowledge base in your browser (page written by the agent)
knosis mcp --ws <dir>                                      # expose the knowledge layer and tools over MCP (16 tools)

Merged or compacted units are never deleted; they stay as aliases of the unit that covers them. When a unit is retracted, the units derived from it must be invalidated too (the check reports them).

Knowledge system: multiple forms, stored and visualized

Knowledge is more than a list. Consolidation organizes the same units into several forms, each answering a different question. All of them are files in the knowledge base, and every node, edge and step cites the units it comes from (no new claims are added; Knosis checks the citations):

Knowledge bases from several datasets can be merged into one (knosis kb merge --namespace) and consolidated again to find entities and knowledge shared across datasets.

Viewing and visualization:

knosis knowledge outline --ws <dir>                       # outline rendered as markdown
knosis knowledge graph   --ws <dir>                       # summary of the knowledge graph and flows
knosis knowledge graph   --ws <dir> --entity <entity> --depth 2   # subgraph around one entity, edges with their units
knosis knowledge graph   --ws <dir> --view flows|derivation|cards
knosis knowledge view    --ws <dir>                       # the agent writes a self-contained page (view/index.html), opened in your browser
knosis knowledge view    --ws <dir> --request "only knowledge about orders"   # regenerate with your own focus

knowledge view has the agent read the knowledge base and write an offline HTML page (outline, knowledge graph, flows, derivation graph; click any unit to see its content and evidence). Knosis checks that the page loads nothing from the network and that the knowledge was not changed, then opens it; later runs just open it, --refresh regenerates it. Agents read the same content through the MCP tools knowledge_outline and knowledge_graph. The live demo renders the knowledge graphs, flows, derivation graphs, cards and outlines of each dataset as interactive pages, plus an atlas merged from several datasets.

Supported data

Knosis targets heterogeneous data: one knowledge layer (κ + evidence + ontology) covers the data types below, each with evaluable data entries and matching tools.

Scenarios, metrics, dev splits and known limitations of each entry are in docs/datasets.md. knosis list lists all entries, knosis describe <name> shows the data card, knosis download <name> fetches the data (datasets are not shipped with the package). Tools (knosis tool list, knosis tool card <name>) only produce knowledge to be verified; they never modify the data.

Documentation

License

Code: Apache-2.0. Datasets and model weights have their own licenses, see datacards/ and each tool's TOOL.md; Knosis does not distribute data or weights.