agent-knowledge-cli

agent-knowledge

Persistent, file-based project memory for AI coding agents.

One command gives any project a knowledge vault that agents read on startup, maintain during work, and carry across sessions -- no database, no server, just markdown files and a CLI.

Works with Claude Code, Cursor, and Codex out of the box.

Install

pip install agent-knowledge-cli

PyPI package name: agent-knowledge-cli. CLI command and all docs: agent-knowledge.

Quick Start

cd your-project
agent-knowledge init

That's it. Open the project in Claude Code or Cursor and the agent has persistent memory automatically -- no manual prompting, no config, no setup.

init does everything in one shot:

• creates an external knowledge vault at ~/agent-os/projects/<slug>/
• symlinks ./agent-knowledge into the repo as the local handle
• installs project-local integration for both Claude Code and Cursor
• detects Codex and installs its bridge files if present
• bootstraps the memory tree and marks onboarding as pending
• imports repo history into Evidence/ and backfills lightweight history from git

Storage modes

By default, knowledge lives outside the repo at ~/agent-os/projects/<slug>/ and ./agent-knowledge is a symlink to it (external mode). To keep knowledge inside the repo and commit it to git, use --local:

agent-knowledge init --local

In local mode:

• ./agent-knowledge/ is a real directory tracked by git
• ~/agent-os/projects/<slug>/ is a symlink pointing back into the repo
• Noisy subfolders (Evidence/raw/, Sessions/, Outputs/site/, ...) are added to .gitignore automatically
• Curated knowledge (Memory/, History/, Evidence/imports/, Dashboards/) is committed normally

To convert an existing project from external to local:

agent-knowledge migrate-to-local

How It Works

Knowledge lives in ./agent-knowledge/ (in-repo or external symlink depending on mode) so every tool always has a stable local handle, regardless of branch, clone, or agent.

Knowledge layers

Evidence is never auto-promoted into Memory. Outputs are never treated as truth. Only agents and humans deliberately write to Memory or History.

Project-local integration

The project carries everything it needs. Both Claude Code and Cursor get full integration installed automatically -- hooks, runtime contracts, and slash commands. No global config required.

Obsidian-ready

The knowledge vault at ~/agent-os/projects/<slug>/ is a valid Obsidian vault. Open it directly for backlinks, graph view, and note navigation.

For a spatial canvas of the knowledge graph:

agent-knowledge export-canvas
# produces: agent-knowledge/Outputs/knowledge-export.canvas

The vault is designed to work well in Obsidian -- good markdown, YAML frontmatter, branch-note convention, internal links. But everything works without it too.

What gets installed

Claude Code (.claude/):

Cursor (.cursor/):

Codex (.codex/) -- installed when detected:

Session lifecycle

Hooks fire automatically -- the agent syncs memory at the start of every session
and captures state at the end, with no manual intervention:

The runtime contract ensures the agent reads STATUS.md and Memory/MEMORY.md at the start of every session, with no manual prompting required.

Slash commands

Inside any Claude Code or Cursor session:

• /memory-update -- sync, review session work, write stable facts to Memory/, summarize
• /system-update -- refresh integration files to the latest framework version

These are project-local and work automatically because init installed them.

Integration health

agent-knowledge doctor

Reports whether all integration files (settings, hooks, rules, commands) are installed and current for both Claude Code and Cursor. If anything is stale or missing, doctor tells you exactly what to run.

Commands

All write commands support --dry-run and --json. Run agent-knowledge --help for the full list.

After upgrading agent-knowledge-cli, run this inside each project to pull in the latest hooks, rules, and commands:

agent-knowledge refresh-system --project .

Static site export

Build a polished standalone site from your knowledge vault -- no Obsidian required:

agent-knowledge export-html       # generate
agent-knowledge view              # generate and open in browser

The generated site includes an overview page, branch tree navigation, note detail view, evidence view, interactive graph view, and machine-readable knowledge.json and graph.json. Opens via file:// with no server needed.

Memory/ notes are always primary. Evidence and Outputs items are clearly marked non-canonical.

Automatic capture

Every sync and update event is automatically recorded in Evidence/captures/ as a small structured YAML file. This gives a lightweight history of what changed and when -- without a database or background service.

Captures are evidence, not memory. They accumulate quietly and can be pruned with agent-knowledge compact.

Progressive retrieval

The knowledge index (Outputs/knowledge-index.json and .md) is regenerated on every sync. Agents can:

1. Load the index first (cheap, a few KB)
2. Identify relevant branches from the shortlist
3. Load only the full note content they actually need

Use agent-knowledge search <query> for a quick shortlist query from the command line or a hook.

Clean web import

Import a web page as cleaned, non-canonical evidence:

agent-knowledge clean-import https://docs.example.com/api-reference
# produces: agent-knowledge/Evidence/imports/2025-01-15-api-reference.md

Strips navigation, ads, scripts, and boilerplate. Writes clean markdown with YAML frontmatter marking it as non-canonical.

Project history

init automatically backfills a lightweight history layer when run on an existing repo. You can also run it explicitly:

agent-knowledge backfill-history

Creates History/events.ndjson (append-only event log), History/history.md (human-readable summary), and History/timeline/ (sparse milestone notes).

History records what happened over time -- releases, integrations, sync events. It is not a git replacement. Current truth lives in Memory/.

Keeping up to date

pip install -U agent-knowledge-cli
agent-knowledge refresh-system

refresh-system updates all integration files -- Claude settings/commands/contract, Cursor hooks/rules/commands, AGENTS.md header, Codex config -- and version markers. It never touches Memory/, Evidence/, Sessions/, or any curated knowledge.

doctor warns when the project integration is behind the installed version.

Custom knowledge home

export AGENT_KNOWLEDGE_HOME=~/my-knowledge
agent-knowledge init

Troubleshooting

agent-knowledge doctor          # validate setup and report health
agent-knowledge doctor --json   # machine-readable health check

Common issues:

• ./agent-knowledge missing: run agent-knowledge init (or agent-knowledge init --local to keep knowledge in the repo)
• Knowledge not in git: run agent-knowledge migrate-to-local to switch to local mode
• Onboarding still pending: paste the init prompt into your agent
• Claude not picking up memory: check .claude/settings.json exists -- run agent-knowledge refresh-system
• Cursor hooks not firing: check .cursor/hooks.json exists -- run agent-knowledge refresh-system
• Stale index: run agent-knowledge sync
• Large notes: run agent-knowledge compact
• Wrong binary: another tool may install a Node.js agent-knowledge that shadows ours. Check with which -a agent-knowledge. Fix: export PATH="$(python3 -c 'import sysconfig; print(sysconfig.get_path("scripts"))'):$PATH"

Platform support

• macOS and Linux are fully supported.
• Windows is not currently supported (relies on bash and POSIX shell scripts).
• Python 3.9+ required.

Package naming

Development

git clone <repo-url>
cd agent-knowledge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -q