ObsDog Docs · Overview

From storing documents
to improving knowledge.

ObsDog is a local-first knowledge repository for people and AI. It measures what was retrieved, noisy, used, and useful—not only what exists.

Quick Start · Install
Local first Block native Human + AI
Landscape

ObsDog connects the gaps between existing tools.

It does not merely reproduce a document editor or an LLM tracing tool. ObsDog connects knowledge itself with evidence of how that knowledge performs in real work.

ServiceWhat it does wellThe connection ObsDog adds
Local knowledge graphObsidian

Markdown, links, plugins, and personal knowledge workflows

Search exposure, use, and usefulness measurement are not its primary scope

Authoring, sharing, permissions, page analytics, and team workflows

They do not center one evidence chain across block revisions and AI retrieval

Model calls, retrieval traces, datasets, and evaluations

Long-lived human knowledge history and maintenance are not the primary object

Knowledge observabilityObsDog

Connect docs, blocks, retrieval, use, evaluation, and change through stable identity

Public local CLI beta with limited, quota-bound hosted registration

Why it is different

The differentiator is the connection, not one isolated feature.

Stable knowledge identity

Nested authored blocks preserve identity and lineage as they move and change.

Evidence, not inference

A retrieved block is never silently promoted to used or useful.

Feedback becomes maintenance

Useful, not useful, noise, verification, and reasons feed actionable review queues.

Humans and AI, explicitly

Human, agent, system, and evaluator activity remain attributable and distinct.

Measurement contract

Five distinct states explain whether knowledge worked.

  1. 01
    retrieved

    Returned as a search candidate

  2. 02
    exposed

    Shown to a person or agent

  3. 03
    selected

    Deliberately chosen

  4. 04
    used

    Cited, copied, linked, or applied

  5. 05
    useful

    Evaluated as helpful for the task

Each state is an independent observation. Exposed does not mean used, and used does not guarantee useful. Living memory in CLI v0.2.0 reinforces and fades traces from actual use and feedback for the same query cue and current revision. Search influence stays within ±20%; --ranking lexical keeps the baseline. Unused is not unhelpful and sources are never deleted by decay. The web knowledge map shows only authored document references as links. Search and use activation remain separate dashboard signals.

Source-aware care

Keep sources authoritative and judgments evidenced.

When the maintained answer lives in code or repository docs, keep it there. ObsDog retains a useful pointer, synthesis or permitted snapshot. AI reads the current revision, makes the smallest justified change and records source or authoring assessments as separate metadata. People inspect state and evidence in Wiki, the knowledge map and the dashboard.

native

Space-owned decisions and reusable knowledge

pointer

The maintained source and the question it answers

derived

Additional synthesis or learning with attributed sources

snapshot

A permitted copy with an exact version and limitations

current, historical and working describe intent. Keep historical context distinct from today's answer without pruning revisions or audit history. Assess home, fidelity, applicability, context and connections with reasons and evidence. Unknown, N/A and unassessed are not passes; authoring assessments are not actual task usefulness.

obsdog care show --format json
obsdog search --source-role pointer --temporal current "installation"
obsdog care record --file care.json --actor-type agent --actor your-agent --format json

Requires CLI v0.2.0 and server v0.1.26+. Identical request retries are not duplicate samples. Content changes leave earlier assessments attached to their original revision; concurrent judgments remain conflicts. This does not enable a crawler, background AI, ranking boosts or automatic deletion.

JSON contract and safe AI workflow
Local setup

Set up the CLI and your AI plugin together.

Choose Codex or Claude Code on Apple silicon macOS or Linux x64 to prepare the CLI and agent plugin together. A compatible existing CLI is reused; local data stays in ~/.obsdog.

Recommended · CLI + AI plugin

One setup. Then inspect your local knowledge.

Apple silicon macOS · Linux x64. Requires your chosen agent CLI (Codex or Claude Code). A missing ObsDog CLI is installed with Homebrew on macOS or the standalone installer on Linux.

Codex
curl -fsSL https://obsdog.ai/install.sh | sh -s -- --client codex
Claude Code
curl -fsSL https://obsdog.ai/install.sh | sh -s -- --client claude

After setup, run obsdog version and obsdog document list. In a fresh agent session, invoke ObsDog find. An empty list is normal.

obsdog version
obsdog document list
obsdog dashboard serve

Review the executed setup script · Review first-party entry · Agent setup guide

CLI-only is supported

Start without a plugin

Use Homebrew on macOS or the standalone installer on Linux x64 for CLI-only setup. A macOS standalone installer is also available in the release. Do not install both methods.

macOS · Homebrew
brew install obsdoghq/tap/obsdog
obsdog document list
Linux x64 · Standalone
curl -fsSL https://github.com/obsdoghq/obsdog-releases/releases/latest/download/install.sh | sh

Local Linux use requires no GUI or account. Cloud login on Linux requires an unlocked Secret Service session.

No init required. Personal is shared across directories and stays in ~/.obsdog. Setup does not create knowledge or upload it to the cloud.

Homebrew update: brew upgrade obsdoghq/tap/obsdog. Standalone update: obsdog update. Restart running MCP and local dashboard processes after upgrading. Plugin-only installation does not install the CLI.

Latest CLI release and standalone installer

Cloud access is a limited beta with capacity and usage limits; registration may pause. The macOS desktop app is not publicly distributed yet.

No init or filesystem Space selector is required. Personal is shared across directories. Setup does not create or sync documents or edit global agent instructions. Review the optional instructions separately in the setup guide; plugins remain optional for CLI-only users.

Choose your first knowledge deliberately.

Even if GitHub, Slack or repositories are connected, installation does not read or upload them. First ask your AI to propose reusable candidates with an authorized source, target Space and checked date. Import only the ones you select; maintained originals stay at their source.

Help me bootstrap ObsDog, but do not import anything yet. From only the sources I authorize, propose up to five reusable notes or source pointers. Show each canonical source, checked date, target Space and privacy boundary. Save only what I choose.
Read the optional bootstrap guide
Personal free beta

Free locally. Connected within clear limits.

Hosted beta signups are controlled within enforced limits and may pause at capacity. No payment method and no automatic paid conversion.

Local$0

Store, search and evaluate knowledge with the CLI, without an account or service-imposed local usage quota. A public Mac app download is still in preparation.

Knowledge stays on your device
Personal free beta$0
  • One Personal Space
  • Three connected device sessions
  • 500 MiB cloud storage
  • 10,000 sync operations per month
Initial capacity: 100 accounts · No hosted AI credit

Storage includes retained history, measurements and sync copies. Monthly usage resets on the first day of each month at 00:00 UTC; exact retries are not counted twice. Reading, export and local work stay available at the limit. New organizations and paid plans are coming later.

Product status

Start by making solo local use excellent.

Foundation today
  • Account-free SQLite and FTS5 local CLI
  • Stable blocks, revisions, labels, and comments
  • Search traces, four rubrics, backup and restore
  • Explicit Personal sync and history-preserving adoption
  • Authenticated web Wiki, knowledge map and offline cache
Next milestones
  • Fresh-account and independent-network beta acceptance
  • Web exploration and knowledge maintenance UX
  • Team collaboration workflow acceptance
  • Mac and iOS paused while web UX is validated

The local CLI and Homebrew package are a public free beta. Hosted access is accepting controlled signups within enforced limits; fresh-account external-network verification is in progress. Billing and a public desktop app are not offered.

Observable Docs

Measure whether knowledge works—not merely how much exists.

Explore how search quality, noise, usefulness, and knowledge health connect in your actual Personal Space.

Explore the dashboard