open-knowledge

Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions.

A flat key-value knowledge store designed for AI agents. Stores notes with titles, content, source URLs, and tags. Works with Bun and Node.js.

Install

# Bun
bun add -g @hasna/knowledge

# npm
npm install -g @hasna/knowledge

Or run directly:

bun x @hasna/knowledge add "My Note" "Some content"

Quick Start

# Add a note
open-knowledge add "Rust ownership" "Every value has exactly one owner"

# List all notes
open-knowledge list

# List with search
open-knowledge list --search ownership

# List notes tagged "rust"
open-knowledge list --tag rust

# Get a note
open-knowledge get --id <id>

# Update a note
open-knowledge update --id <id> --title "Rust ownership model"

# Delete a note (requires --yes)
open-knowledge delete --id <id> --yes

# Export all notes as JSONL
open-knowledge export --format jsonl

Commands

add

open-knowledge add <title> <content> [--url <url>] [-t <tag>]

Add a new knowledge item.

list

open-knowledge list|ls [options]

List items with pagination, search, and tag filtering.

| Flag | Description | |------|-------------| | -p, --page <n> | Page number (default: 1) | | -l, --limit <n> | Items per page (default: 20) | | -s, --search <text> | Filter by title or content | | -t, --tag <tag> | Filter by tag | | --sort created\|title | Sort field (default: created) | | --desc | Sort descending |

get

open-knowledge get --id <id>

Retrieve a single item by ID.

update

open-knowledge update|edit --id <id> [options]

Update an existing item.

| Flag | Description | |------|-------------| | --title <title> | New title | | --content <content> | New content | | --url <url> | New source URL | | -t, --tag <tag> | Add a tag |

delete

open-knowledge delete|rm --id <id> --yes

Delete an item. Requires --yes to confirm.

export

open-knowledge export [--format jsonl]

Export all items. Use --format jsonl for newline-delimited JSON.

help

open-knowledge help [command]

Global Options

| Flag | Description | |------|-------------| | --json | Output raw JSON | | --store <path> | Override store path | | --version, -v | Show version | | --help, -h | Show help |

Store Location

Default store: ~/.open-knowledge/db.json

Override with --store <path> or set OPEN_KNOWLEDGE_STORE env var.

JSON Output

Every command returns structured JSON when --json is passed:

{
  "ok": true,
  "item": { "id": "...", "title": "...", "content": "...", "url": null, "tags": [], "created_at": "...", "updated_at": "..." }
}

Agent-Friendly Design

• JSON-only mode: --json flag for easy parsing by LLMs
• Idempotent IDs: each item gets a stable unique ID
• Safe deletes: --yes flag required; no accidental deletions
• Concurrent-safe: file locking prevents corruption from parallel agents
• Scriptable: works in pipelines, CI, and any automation tool