Owledge

Drop-in durable project memory for existing Markdown repos and Obsidian-style vaults: no migration, no vector DB, no wiki-link rewrite.

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

Use it when agents are losing project context, plans are stuck in chat, multiple runtimes need a shared handoff surface, or a mature knowledgebase needs traceable decisions without a migration.

Core idea: Markdown is the source of truth; indexes, reports, graphs, benchmarks, and runtime adapters are generated or optional views.

Release proof: local release gates pass with additive writes by default, private runtime capture, metadata-first KB scan, and no required OS-wide setup. CI runs platform-neutral Python gates; broader runtime installs remain local adapter support, not marketplace certification.

Minimal by default: start with principles and skills only. Add project files,
runtime adapters, or add-ons only when the current project needs durable local
artifacts, runtime capture, proof assets, or release evidence.

Repo Layout

This repository ships product source from templates/owledge/. The
internal/owledge/ directory is the maintainers' dogfood workspace
(generated artifacts, not shipped). The tools/ directory holds the Python
CLI. See docs/distribution.md for the full
Dogfooding vs. Product breakdown.

Table Of Contents

• Why It Exists
• Problem To Solution
• Install Or Try
• 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

Install Or Try

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

Fastest proof path:

uvx owledge quickstart --target .agent-control/tmp/owledge-five-minute-demo
owledge install-addon --project-root .agent-control/tmp/owledge-five-minute-demo --addon launch-demo-kit
owledge 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. 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. It adds project-local Markdown memory and
Python tools without changing the host framework, package manager, or source
tree.

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: Plugin / Harness Setup

Use the ready-to-install Cowork / Claude-compatible plugin bundle:

plugins/owledge-cowork/

Best next read: Plugin install guide

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"]

Read-Only MCP

Owledge ships a read-only MCP surface in v0.7.0.

flowchart LR
    A["Agent harness"] --> B["Owledge read-only MCP"]
    B --> C["Read OWLEDGE.md"]
    B --> D["Search memory"]
    B --> E["Build context pack"]
    B --> F["List tasks and reviews"]
    C --> G["No write tools in P0"]

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

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