Metadata-Version: 2.4
Name: owledge
Version: 0.8.0
Summary: Markdown-first durable memory for AI agents, existing repos, and knowledgebases.
Author: Owledge maintainers
License-Expression: MIT
Project-URL: Documentation, https://github.com/elmokirk/owledge/tree/main/docs
Project-URL: Issues, https://github.com/elmokirk/owledge/issues
Project-URL: Source, https://github.com/elmokirk/owledge
Keywords: owledge,ai-agents,markdown,codex,claude-code,knowledge-base
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Owledge

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

[![Version](https://img.shields.io/badge/version-0.8.0-blue)](VERSION)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Storage: Markdown](https://img.shields.io/badge/storage-Markdown-black)](docs/quickstart.md)
[![V1 candidate](https://img.shields.io/badge/V1-local%20minimal%20Core-orange)](docs/v1-minimal-core.md)
[![CI](https://github.com/elmokirk/owledge/actions/workflows/ci.yml/badge.svg)](https://github.com/elmokirk/owledge/actions/workflows/ci.yml)
[![Docs](https://github.com/elmokirk/owledge/actions/workflows/docs.yml/badge.svg)](https://github.com/elmokirk/owledge/actions/workflows/docs.yml)

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

| If this is your problem | Owledge gives you |
| --- | --- |
| The next agent must rediscover decisions | A Markdown handoff with sources, decisions, and the next action. |
| A plan needs to survive implementation and review | Evidence-linked plans, checks, and explicit stop points. |
| You want structure without migrating a repo or vault | An additive local layer; Markdown remains canonical. |

**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](docs/security/local-http-control-plane.md).

**Next action:** read the [V1 Minimal Core boundary](docs/v1-minimal-core.md), then choose a [smallest integration](docs/integration-decision-guide.md). Install only when that path calls for it.

## The mental model

```text
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?](docs/what-is-owledge.md) for privacy, non-goals, capability maturity, and the complete lifecycle.

## Table Of Contents

- [Why It Exists](#why-it-exists)
- [Problem To Solution](#problem-to-solution)
- [Choose Your Path](#choose-your-path)
- [Quickstart Paths](#quickstart-paths)
- [Decision Guide](#decision-guide)
- [Before / After](#before--after)
- [Harness Support](#harness-support)
- [Integration Model](#integration-model)
- [Performance And Token Model](#performance-and-token-model)
- [Core Workflows](#core-workflows)
- [Standalone Skills](#standalone-skills)
- [Troubleshooting](#troubleshooting)
- [Not This](#not-this)
- [Launch Extensions](#launch-extensions)
- [Quality Gates](#quality-gates)
- [Documentation](#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

| Problem | Owledge solution |
| --- | --- |
| Agents forget context between sessions | `OWLEDGE.md` plus `.owledge/` creates a durable project entrypoint and memory layer. |
| Plans live only in chat | `.owledge/plans/`, `.owledge/tasks/`, and `.owledge/workpackages/` keep scoped work visible and reviewable. |
| Handoffs are vague | `.owledge/handoffs/` and context packs give the next agent explicit source files, decisions, and next actions. |
| Docs and implementation drift | `doctor`, `test-contracts`, `public-docs`, `release-trust`, and finalization gates catch stale public claims. |
| Obsidian links are fragile | `owledge wikilink-audit` checks valid, broken, and ambiguous wiki links without rewriting notes. |
| Users doubt token efficiency | Optional `benchmark-kit` add-on emits real Markdown fixture reports with token usage, performance, context pollution, retrieval, safety, and speed metrics. |
| Users want one skill without the full kit | `standalone-skills/` provides independently installable Owledge skills for blindspot audit, agentic review, brainstorm, and planning layer use. |
| Teams need review and research traceability | `.owledge/reviews/`, `.owledge/audiences/`, and `.owledge/research/` make red-team, audience, and research artifacts first-class. |

## 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?](docs/what-is-owledge.md)
- **Use the operating rules in an existing system:** [Integration Decision Guide](docs/integration-decision-guide.md)
- **Add durable project artifacts:** [Installation Hub](docs/install/README.md)
- **Try a bounded demo:** [Try Owledge in 5 minutes](docs/try-owledge-in-5-minutes.md)
- **Inspect current capability maturity:** [Public capability registry](contracts/public-capabilities.json)

## Install Or Try

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

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

For repeated use:

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

Source checkout remains useful for contributors:

```bash
python tools/owledge.py --help
```

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

```bash
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](docs/install/README.md) for the package path. Full
walk-through: [Try Owledge in 5 minutes](docs/try-owledge-in-5-minutes.md).

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](benchmarks/v0.7.0/README.md)
- [HTML comparison report](benchmarks/v0.7.0/results/comparison/index.html)
- [Methodology](benchmarks/v0.7.0/methodology.md)
- [Injected benchmark traps](benchmarks/v0.7.0/benchmark-explained.md)

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`:

```text
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:

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

Source checkout path:

```bash
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](docs/quickstart.md)

### 2. Add Owledge To A Knowledgebase

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

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

Best next read: [Drop-in agent integration guide](docs/agent-integration-guide.md)

### 3. Check An Existing Install

Verify any initialized project:

```bash
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](docs/harness-plugin-matrix.md)

### Optional: Project Snapshot Kit

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

```bash
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:

```bash
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:

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

| Path | Use when | Adds |
| --- | --- | --- |
| Principles-only / Skills | An agent needs the memory rules inside an existing workflow | Instructions only |
| Project-local kit | A repo needs durable plans, evidence, handoffs, indexes, and validation | Local Markdown memory and Python tools |
| Knowledgebase module | An existing Markdown or Obsidian-style vault should be scanned without migration | Additive module or mapped indexes |
| Runtime adapter | Session capture, hooks, or runtime handoffs are needed | Optional plugin files and hooks |
| Planning layer skill | A project already has its own `AGENTS.md` or agent memory and should keep it | Opt-in Owledge planning, evidence, handoff, and context hygiene rules |
| Add-ons | Demo, trust, conformance, PI proof, TS eval, benchmark, decision trace, cross-project hub, swarm coordination, or positioning evidence is needed | Optional docs, fixtures, tools, and generated views |

Detailed guide: [Integration decision guide](docs/integration-decision-guide.md).

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

| Harness | Current shape | Install path |
| --- | --- | --- |
| Principles-only coding agents | First-class support | Instructions or `owledge-principles` skill |
| Codex | Local adapter support | Local CLI, skills, optional plugin adapter |
| Claude Code | Local adapter support | Skill/plugin copy path plus project-local memory rules |
| Generic MCP/CLI | Local reference adapter | Project-local bridge with five tools; Candidate-only write |
| Existing Markdown / Obsidian KBs | Primary supported path | `tools/build_kb_module.py`, `owledge-map.json`, and `wikilink-audit` |
| PI agents | Advanced optional path | Candidate-only QA, workspace checks, and intelligence artifacts |

Full matrix: [Harness and plugin matrix](docs/harness-plugin-matrix.md)

## Integration Model

| Mode | What changes | Best fit |
| --- | --- | --- |
| Principles-only | Agent instructions adopt the Owledge memory contract without adding a plugin; no plugin, generator, wrapper, or OS-specific setup is required | Existing coding agents and mature repos |
| Project-local kit | Adds `OWLEDGE.md`, `.owledge/`, local Python tools, and optional runtime adapter files | Coding projects that want durable memory in-repo |
| Knowledgebase module | Adds an Owledge-owned module or mapped folders beside an existing Markdown KB | Obsidian-style vaults and LLM wikis |
| Reference adapter | Bridges the same local Core into Codex, Claude Code, or generic MCP/CLI | Local workflows that need a supported harness surface |

## Performance And Token Model

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

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

| Area | Current release behavior |
| --- | --- |
| KB scan | Metadata-first by default; no body-copy migration |
| Token strategy | Paths and refs first, full bodies only on demand |
| Write policy | Additive module or mapped writes; existing notes unchanged by default |
| Scale guard | `--max-files`, excluded generated dirs, truncation reporting |
| Benchmarks | Optional `benchmark-kit` add-on with real Markdown fixtures, deterministic CI mode, opt-in sequential Ollama local mode, and multi-model comparison reports |

Benchmarks and scale notes: [Performance and scale notes](docs/performance-scale-notes.md)

## Core Workflows

### Project Setup

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

```mermaid
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

```mermaid
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

```mermaid
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

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

| Skill | Use |
| --- | --- |
| `owledge-blindspot-audit` | Stress-test a concept, repo, plan, or launch surface for hidden gaps. |
| `owledge-agentic-review` | Run evidence-linked red-team and expert review workflows. |
| `owledge-brainstorm` | Generate candidate options without mutating canonical memory. |
| `owledge-long-horizon-delivery` | Keep planning bounded to an MVP, reflect after every version, and route future ideas durably. |
| `owledge-planning-layer` | Apply Owledge planning, handoff, and QA rules in an existing agent setup. |

See [standalone-skills/README.md](standalone-skills/README.md).

### Handoff And Resume

```mermaid
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

| Symptom | Check |
| --- | --- |
| `owledge` command not found | Run `uvx owledge --help` or `uv tool install owledge`. |
| Fresh project has old `OWLEDGE.md`/`.owledge/` | Re-run the documented `owledge init --target <path>` profile and check for `OWLEDGE.md` plus `.owledge/`. |
| Wikilink audit fails | Run `owledge wikilink-audit --project-root .` and fix unresolved or ambiguous targets. Code blocks and inline code are ignored. |
| Local benchmark refuses to run | Install `benchmark-kit`, then pass explicit scale mode, model, and consent: `python tools/benchmark-kit/run-benchmark-kit.py --mode local --scale-mode small --models gemma4:latest --yes`. |
| Generic MCP/CLI needs a write | Use only the explicit Candidate proposal tool; review/promotion stays revision-bound and Core-owned. |
| Docs look stale after code changes | Run `owledge test public-docs`, `owledge test release-trust`, and `owledge wikilink-audit --check`. |

## Not This

Owledge is not:

- a hosted platform
- a production or remote team server; optional `serve` is
  [local experimental and loopback-only](docs/security/local-http-control-plane.md)
- 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:

| Add-on | Purpose |
| --- | --- |
| `launch-demo-kit` | Five-minute demo with evidence, handoff, and static proof report. |
| `trust-readiness-kit` | Data-flow, threat model, security FAQ, and team checklist. |
| `runtime-conformance-kit` | Read-only runtime contracts for Codex, Claude Code, and Cowork-compatible adapters. |
| `pi-proof-kit` | Synthetic PI loop proving observe, detect, red-team, promote, and measure. |
| `ts-adapter-kit` | Optional Node/TypeScript CI validation for the Markdown contract. |
| `benchmark-kit` | Optional real Markdown fixture benchmark with token, performance, context pollution, single-run reports, and multi-model comparison proof reports. |
| `decision-trace-kit` | Read-only JSON and HTML trace from memory records to decision tree. |
| `cross-project-hub-kit` | Reviewed export map from project-local lessons, patterns, decisions, and summaries into a central reusable hub. |
| `swarm-coordination-kit` | Role-lane templates for Codex, Claude Code, Hermes, and generic agent swarms without hard distributed locking. |
| `poweruser-positioning-kit` | Snapshot-first positioning scorecard for adjacent AI-agent tool categories. |

Launch scoring and pass/fail criteria: [Launch readiness rubric](docs/launch-readiness.md). Distribution path: [Distribution and release](docs/distribution.md).

## Quality Gates

Release validation is scriptable and local:

```bash
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:

```bash
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](docs/README.md)

- [Quickstart](docs/quickstart.md)
- [Integration decision guide](docs/integration-decision-guide.md)
- [Try Owledge in 5 minutes](docs/try-owledge-in-5-minutes.md)
- [Launch readiness rubric](docs/launch-readiness.md)
- [Distribution and release](docs/distribution.md)
- [Drop-in agent integration guide](docs/agent-integration-guide.md)
- [Plugin install guide](docs/install-plugin.md)
- [Harness and plugin matrix](docs/harness-plugin-matrix.md)
- [MVP plan example](docs/mvp-plan-example.md)
- [Demo vault](examples/README.md)
- [Performance and scale notes](docs/performance-scale-notes.md)
- [Benchmark Kit](docs/benchmark-kit.md)
- [Team and long-running project guide](docs/team-long-running-project-guide.md)
- [Command reference](docs/command-reference.md)
- [Project Snapshot Kit](docs/project-snapshot-kit.md)
- [Decision Trace Kit](docs/decision-trace-kit.md)
- [Benchmark Kit](docs/benchmark-kit.md)
- [Cross-Project Hub Kit](docs/cross-project-hub-kit.md)
- [Swarm Coordination Kit](docs/swarm-coordination-kit.md)
- [Poweruser Positioning Kit](docs/poweruser-positioning-kit.md)
- [Standalone Skills](standalone-skills/README.md)
- [Owledge vs agent methods](docs/owledge-vs-agent-methods.md)
