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