Owledge

An Agentic Engineering Context & Planning Layer for teams that want agents to ship durable work, not lose it in chat.

Owledge gives agents durable local Markdown artifacts: plans, evidence, reviews, handoffs, and decisions that stay readable across sessions and existing vaults.

Use it when agents lose project context, plans get stuck in chat, or a Markdown repository needs a reviewable handoff surface. It is additive: existing files stay yours.

In five seconds

V1 boundary: the local Minimal Core supports Principles, project_user, an explicitly linked private user_global, and Codex, Claude Code, or generic MCP/CLI bridges. It is not a hosted Team Hub, remote sync, a background scheduler, or a replacement for your issue tracker. The current HTTP adapter is local experimental and loopback-only.

Next action: read the V1 Minimal Core boundary, then choose a smallest integration. Install only when that path calls for it.

The mental model

intent -> project truth -> scoped context -> agent work -> evidence and handoff -> reviewed promotion

Markdown is the source of truth. Indexes, reports, graphs, benchmarks, and runtime adapters are generated or optional views. A person remains responsible for project decisions and promotion.

Read What is Owledge? for privacy, non-goals, capability maturity, and the complete lifecycle.

Table Of Contents

• Why It Exists
• Problem To Solution
• Choose Your Path
• Quickstart Paths
• Decision Guide
• Before / After
• Harness Support
• Integration Model
• Performance And Token Model
• Core Workflows
• Standalone Skills
• Troubleshooting
• Not This
• Launch Extensions
• Quality Gates
• Documentation

Why It Exists

Owledge is for teams and power users who already work in Markdown, Obsidian, LLM wikis, or agent-driven coding repos and need project context to survive beyond one chat session.

• Keep context durable instead of rebuilding it from transcript history.
• Keep MVP plans grounded with evidence, cutlines, reviews, and handoffs.
• Fit existing knowledgebases without rewriting wiki links or note structure.
• Let multiple agents coordinate through explicit artifacts instead of raw logs.
• Stay local, inspectable, and repo-friendly.

Problem To Solution

Choose Your Path

Start with the smallest path that solves the current problem. Each route stays within two clicks of its canonical guide.

• Understand first: What is Owledge?
• Use the operating rules in an existing system: Integration Decision Guide
• Add durable project artifacts: Installation Hub
• Try a bounded demo: Try Owledge in 5 minutes
• Inspect current capability maturity: Public capability registry

Install Or Try

Once you chose a path, Owledge is uv-first for agents and harnesses:

uvx owledge --help
uvx owledge quickstart --target .agent-control/tmp/owledge-five-minute-demo

For repeated use:

uv tool install owledge
owledge doctor --project-root .
owledge doctor --project-root /path/to/your-project

Source checkout remains useful for contributors:

python tools/owledge.py --help

Source-checkout demo path (optional add-on):

python tools/owledge.py quickstart --target .agent-control/tmp/owledge-five-minute-demo
python tools/owledge.py install-addon --project-root .agent-control/tmp/owledge-five-minute-demo --addon launch-demo-kit
python tools/owledge.py doctor --project-root .agent-control/tmp/owledge-five-minute-demo

Expected result: the demo project contains evidence, a next-agent handoff, and a static proof report. This is not a package-only recipe; use the Installation Hub for the package path. Full walk-through: Try Owledge in 5 minutes.

Benchmark proof:

On the v0.7.0 synthetic Markdown fixture, Owledge reduced context pollution by 88.36% on average and reduced tokens per correct answer by 83.54% on average against the naive baseline. Real-world savings vary by vault shape, model, runtime, and retrieval configuration.

• v0.7.0 benchmark summary
• HTML comparison report
• Methodology
• Injected benchmark traps

The published runs use deterministic test vaults, not a personal vault. The privacy-trap baseline is expected to fail; the product proof is whether the Owledge context-pack profile keeps private and stale notes out.

Quickstart Paths

0. Use Only The Principles Or Skills

For the smallest setup, do not install anything. Tell an agent to follow the Owledge principles or use skills/owledge-principles:

Follow Owledge principles: keep Markdown canonical, preserve existing files,
write evidence-linked plans and handoffs, use stable frontmatter ids and typed
edges, keep raw sessions private, and promote only reviewed memory.

This path is the default for existing systems, solo users, and quick adoption.

1. Add Owledge To A Project

Package path:

uvx owledge quickstart --target /path/to/your-project

Source checkout path:

python tools/owledge.py init-project --target /path/to/your-project

This is the primary setup path. By default it creates only a compact project router and local config; deterministic Python operations are provided by the installed Owledge Core, not copied into the project. Use --profile full from a source checkout only for the larger compatibility/tool-and-skill kit.

Best next read: Project quickstart

2. Add Owledge To A Knowledgebase

Add Owledge as a small additive module inside an existing vault:

python tools/owledge.py add-kb-module --knowledgebase-root /path/to/your/vault

Best next read: Drop-in agent integration guide

3. Check An Existing Install

Verify any initialized project:

python tools/owledge.py doctor --project-root /path/to/your-project

Optional: Reference Harness Setup

Use the project-local Codex, Claude Code, or generic MCP/CLI bridge only after the local Core journey is working. These reference bridges reuse Core behavior; they do not create another memory store.

The canonical legacy plugin path is plugins/owledge-cowork/; it is retained for compatibility but is not a V1 reference-adapter claim.

Best next read: V1 harness boundary

Optional: Project Snapshot Kit

Install the optional project cockpit add-on only when a project should generate reusable snapshots and static HTML pages:

python tools/owledge.py install-addon --project-root . --addon project-snapshot-kit
python tools/owledge.py project-snapshot --project-root .

The generation command asks before creating Markdown snapshots or HTML pages unless explicit non-interactive flags are used.

Optional: Launch Add-ons

Launch add-ons improve distribution readiness without changing the core memory contract:

python tools/owledge.py install-addon --project-root . --addon launch-demo-kit
python tools/owledge.py install-addon --project-root . --addon trust-readiness-kit
python tools/owledge.py install-addon --project-root . --addon runtime-conformance-kit
python tools/owledge.py install-addon --project-root . --addon pi-proof-kit

Additional proof add-ons are available for teams that need TypeScript CI validation, benchmark charts, decision traceability, cross-project reuse, multi-agent handoffs, or poweruser positioning:

python tools/owledge.py install-addon --project-root . --addon ts-adapter-kit
python tools/owledge.py install-addon --project-root . --addon benchmark-kit
python tools/owledge.py install-addon --project-root . --addon decision-trace-kit
python tools/owledge.py install-addon --project-root . --addon cross-project-hub-kit
python tools/owledge.py install-addon --project-root . --addon swarm-coordination-kit
python tools/owledge.py install-addon --project-root . --addon poweruser-positioning-kit

Decision Guide

Use the smallest integration that solves the current problem.

Detailed guide: Integration decision guide.

Before / After

Without Owledge:

• a plan lives in chat
• evidence is scattered across notes and commits
• a second agent has to reconstruct the project state
• handoffs depend on whoever remembers the context

With Owledge:

• plans live in Markdown
• evidence paths are explicit
• handoffs and reviews are durable artifacts
• future agents can resume from scoped files instead of entire chat logs

Harness Support

Owledge is a memory layer around agent runtimes. It does not replace the runtime or its execution methodology.

Full matrix: Harness and plugin matrix

Integration Model

Performance And Token Model

Owledge is designed to avoid the "load the whole vault into context" failure mode.

flowchart LR
    A["Existing repo or vault"] --> B["Metadata-first scan"]
    B --> C["Paths, titles, hashes, refs"]
    C --> D["Scoped context pack"]
    D --> E["Agent loads only relevant source files"]
    E --> F["Plan, evidence, handoff, review"]

Benchmarks and scale notes: Performance and scale notes

Core Workflows

Project Setup

flowchart LR
    A["uvx owledge quickstart"] --> B["OWLEDGE.md"]
    A --> C[".owledge/"]
    C --> D["plans, tasks, reviews, handoffs"]
    C --> E["indexes and generated reports"]
    B --> F["Agent reads scoped project truth"]

Generic MCP/CLI bridge

The V1 generic bridge exposes five Core tools: capabilities, recall, context, propose, and revision-bound review. Only propose can create a private Candidate; promotion remains an explicit Core review.

Historical v0.7 material calls the compatibility route a read-only MCP surface. That route is retained under advanced compatibility only; it is not the V1 generic MCP/CLI contract.

flowchart LR
    A["Agent harness"] --> B["Owledge generic MCP/CLI bridge"]
    B --> C["Read OWLEDGE.md"]
    B --> D["Search memory"]
    B --> E["Build context pack"]
    B --> F["Propose or review Candidate"]
    C --> G["No direct storage or remote write"]

Planning, Review, Research

flowchart TD
    A["Goal or release question"] --> B["Audience profile"]
    B --> C["Research brief or findings"]
    C --> D["Plan and workpackages"]
    D --> E["Agentic review"]
    E --> F["Accepted deltas"]
    F --> G["OWLEDGE.md or canonical memory after review"]

Wikilink Audit

flowchart LR
    A["Markdown files"] --> B["Extract wiki links"]
    B --> C{"Target found?"}
    C -->|Yes| D["Candidate edge"]
    C -->|No| E["Broken link finding"]
    C -->|Multiple| F["Ambiguous link finding"]
    D --> G["Read-only report"]
    E --> G
    F --> G

Benchmark Kit

flowchart LR
    A["install benchmark-kit add-on"] --> B["run-benchmark-kit.py"]
    B --> C{"Mode and scale mode"}
    C -->|ci| D["Generate real Markdown fixtures"]
    C -->|local| E["Scan/use selected Ollama models"]
    C --> I["Scale modes: small, mid, large"]
    E --> F["Sequential model calls"]
    D --> G["Stable metrics"]
    F --> G
    G --> H["JSON, MD, HTML, SVG report"]

Standalone Skills

Owledge also ships selected skills as separate, download-friendly folders under standalone-skills/. Use this when a user wants a single workflow without installing the full project memory kit.

See standalone-skills/README.md.

Handoff And Resume

flowchart LR
    A["Agent finishes phase"] --> B["Write handoff and review evidence"]
    B --> C["Orchestrator summarizes delta"]
    C --> D["Plan/tasklist updated"]
    D --> E["Next agent reads OWLEDGE.md and handoff"]
    E --> F["Resume first unchecked phase"]

Troubleshooting

Not This

Owledge is not:

• a hosted platform
• a production or remote team server; optional serve is local experimental and loopback-only
• a vector database
• an RBAC or enterprise policy system
• a replacement for Superpowers or Ponytail
• a requirement to migrate your existing vault taxonomy

It is a local/project utility layer for durable memory, planning discipline, and agent coordination.

Launch Extensions

The core stays small. Broad-launch proof is handled by optional add-ons:

Launch scoring and pass/fail criteria: Launch readiness rubric. Distribution path: Distribution and release.

Quality Gates

Release validation is scriptable and local:

python tools/owledge.py finalization-gates --project-root . --include-compliance
python tools/owledge.py redteam-qa --project-root .

Public docs are checked separately for encoding, anchors, links, plugin/install consistency, and benchmark asset presence:

python tools/owledge.py test public-docs --project-root .
python tools/owledge.py test quality-ratchet --project-root .
python tools/owledge.py test launch-readiness --project-root .

Release QA

Release QA is contract-backed: contracts/release-surface.json declares every current version sink, public documentation file, and product feature's required documentation and verification. Run the docs-contract against origin/main for a product PR and the release-contract with require-dist before publishing a release branch.

Documentation

Start here: Documentation index

• Quickstart
• Integration decision guide
• Try Owledge in 5 minutes
• Launch readiness rubric
• Distribution and release
• Drop-in agent integration guide
• Plugin install guide
• Harness and plugin matrix
• MVP plan example
• Demo vault
• Performance and scale notes
• Benchmark Kit
• Team and long-running project guide
• Command reference
• Project Snapshot Kit
• Decision Trace Kit
• Benchmark Kit
• Cross-Project Hub Kit
• Swarm Coordination Kit
• Poweruser Positioning Kit
• Standalone Skills
• Owledge vs agent methods