agent-knowledge-cli 0.2.3__tar.gz → 0.2.4__tar.gz

{agent_knowledge_cli-0.2.3 → agent_knowledge_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-knowledge-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: Adaptive, file-based project knowledge for AI coding agents
 Author: agent-knowledge contributors
 License-Expression: MIT
@@ -32,24 +32,22 @@ just markdown files and a CLI.
 
 ## Install
 
-```
+```bash
 pip install agent-knowledge-cli
 ```
 
-This installs the `agent-knowledge` command. PyPI package name is `agent-knowledge-cli`;
-the CLI command and all documentation refer to it as `agent-knowledge`.
+PyPI package name: `agent-knowledge-cli`. CLI command and all docs: `agent-knowledge`.
 
 ## Quick Start
 
 ```bash
-pip install agent-knowledge-cli
 cd your-project
 agent-knowledge init
 ```
 
-Open Cursor in the repo — the agent picks up from there automatically.
+Open Cursor — the agent picks up from there automatically.
 
-`init` installs everything needed in the project:
+`init` does everything in one shot:
 - infers the project slug from the directory name
 - creates an external knowledge vault at `~/agent-os/projects/<slug>/`
 - symlinks `./agent-knowledge` into the repo as the local handle
@@ -58,46 +56,44 @@ Open Cursor in the repo — the agent picks up from there automatically.
 - installs `.cursor/commands/memory-update.md` and `system-update.md` — slash commands
 - detects Claude and Codex and installs their bridge files if present
 - bootstraps the memory tree and marks onboarding as `pending`
-- backfills lightweight history from git (if existing repo)
+- imports repo history into `Evidence/` automatically
+- backfills lightweight history from git
 
 ## How It Works
 
-```
-your-project/
-  .agent-project.yaml        # project config
-  AGENTS.md                   # instructions agents read on startup
-  agent-knowledge/            # symlink -> ~/agent-os/projects/<slug>/
-    STATUS.md                 # onboarding state + sync timestamps
-    Memory/                   # curated, durable knowledge (source of truth)
-      MEMORY.md
-      stack.md
-      decisions/
-        decisions.md
-    Evidence/                 # imported or extracted material (not canonical)
-      raw/
-      imports/
-      captures/               # automatic event stream
-    Outputs/                  # generated views (never canonical)
-      knowledge-index.json
-      knowledge-index.md
-      knowledge-export.html
-    Sessions/                 # ephemeral session state
-```
-
-Knowledge lives **outside** the repo so it persists across branches, tools,
-and clones. The symlink gives every tool a stable `./agent-knowledge` path.
+Knowledge lives **outside** the repo at `~/agent-os/projects/<slug>/` so it persists
+across branches, tools, and clones. The symlink `./agent-knowledge` gives every tool
+a stable local handle.
 
 ### Architecture boundaries
 
 | Folder | Role | Canonical? |
 |--------|------|-----------|
-| `Memory/` | Curated, durable facts -- source of truth | Yes |
+| `Memory/` | Curated, durable facts — source of truth | Yes |
+| `History/` | What happened over time — lightweight diary | Yes (diary) |
 | `Evidence/` | Imported/extracted material, event stream | No |
 | `Outputs/` | Generated views, indexes, HTML export | No |
 | `Sessions/` | Ephemeral session state, prune aggressively | No |
 
 Evidence is never auto-promoted into Memory. Outputs are never treated as truth.
-Only agents and humans deliberately write to Memory.
+Only agents and humans deliberately write to Memory or History.
+
+## 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.
+
+![Obsidian graph view of a project knowledge vault](docs/obsidian-graph.png)
+
+For a spatial canvas of the knowledge graph:
+
+```bash
+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.
 
 ### Automatic capture
 
@@ -120,33 +116,65 @@ on every sync. It provides a compact catalog of all notes so agents can:
 Use `agent-knowledge search <query>` to run a quick Layer 2 shortlist query
 from the command line or a hook.
 
-#
+## Cursor-first runtime
+
+Cursor is the primary supported runtime path. The project carries everything
+it needs — opening the repo in Cursor is enough to get automatic behavior:
+
+| What is installed | What it does |
+|------------------|-------------|
+| `.cursor/rules/agent-knowledge.mdc` | Always-on rule: loads memory context on every session |
+| `.cursor/hooks.json` | Lifecycle hooks: sync on start, update on write, sync on stop and pre-compact |
+| `.cursor/commands/memory-update.md` | `/memory-update` slash command |
+| `.cursor/commands/system-update.md` | `/system-update` slash command |
+
+### Session lifecycle
+
+When you open the project in Cursor, the hooks fire automatically:
+
+- **session-start** — runs `agent-knowledge sync` to load fresh vault state
+- **post-write** — runs `agent-knowledge update` after each file save
+- **stop** — runs `agent-knowledge sync` at end of each task
+- **preCompact** — runs `agent-knowledge sync` before context compaction
+
+The rule 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 Cursor session in this project:
+
+- `/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. They work because `init` installed them in `.cursor/commands/`.
+
+### Integration health
+
+```bash
+agent-knowledge doctor
+```
+
+Reports whether rules, hooks, and commands are all installed and current.
+If any file is stale or missing, `doctor` suggests `agent-knowledge refresh-system`.
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `init` | Set up a project (zero-arg, auto-detects everything) |
-| `sync` | Memory sync + session rollup + git evidence + capture + index |
-| `doctor` | Validate setup and report health |
-| `update` | Sync project changes into the knowledge tree |
-| `import` | Import repo history into Evidence/ |
-| `ship` | Validate, sync, commit, push |
-| `bootstrap` | Create or repair the memory tree |
-| `setup` | Install global Cursor rules and skills |
-| `global-sync` | Import safe local tooling config |
-| `graphify-sync` | Import graph/discovery artifacts |
-| `compact` | Prune stale memory and old captures |
-| `index` | Regenerate the knowledge index in Outputs/ |
+| `init` | Set up a project — one command, no arguments needed |
+| `sync` | Full sync: memory, history, git evidence, index |
+| `doctor` | Validate setup, integration health, version staleness |
+| `ship` | Validate + sync + commit + push |
 | `search <query>` | Search the knowledge index (Memory-first) |
-| `export-html` | Build polished static site in Outputs/site/ |
-| `view` | Build site and open it in the browser |
-| `clean-import <url>` | Import a URL or HTML file as cleaned evidence |
-| `refresh-system` | Refresh integration files to the current framework version |
-| `export-canvas` | Export vault as an Obsidian Canvas file (optional) |
-| `backfill-history` | Backfill lightweight project history from git |
-| `measure-tokens` | Estimate context token savings |
+| `export-html` | Build a polished static site from the vault |
+| `view` | Build site and open in browser |
+| `clean-import <url>` | Import a URL as cleaned, non-canonical evidence |
+| `refresh-system` | Refresh all integration files to the current framework version |
+| `backfill-history` | Rebuild lightweight project history from git |
+| `compact` | Prune stale captures and old session state |
 
-All write commands support `--dry-run`. Use `--json` for machine-readable output.
+All write commands support `--dry-run` and `--json`. Run `agent-knowledge --help` for the full command list.
 
 ## Static site export with graph
 
@@ -227,65 +255,6 @@ Strips navigation, ads, scripts, and boilerplate. Writes clean markdown with
 YAML frontmatter marking it as non-canonical. Verify facts before promoting
 any content to Memory/.
 
-## Obsidian (optional)
-
-Obsidian is an **optional** viewer/editor. agent-knowledge is not Obsidian-centric.
-
-Open `~/agent-os/projects/<slug>/` as an Obsidian vault for backlinks and graph view.
-
-![Obsidian graph view of a project knowledge vault](docs/obsidian-graph.png)
-
-For an optional spatial canvas of the knowledge graph:
-
-```
-agent-knowledge export-canvas
-# produces: agent-knowledge/Outputs/knowledge-export.canvas
-# open in Obsidian with Core plugins > Canvas
-```
-
-All Obsidian-specific features are optional. The system works fully without Obsidian.
-
-## Cursor-first runtime
-
-Cursor is the primary supported runtime path. The project carries everything
-it needs — opening the repo in Cursor is enough to get automatic behavior:
-
-| What is installed | What it does |
-|------------------|-------------|
-| `.cursor/rules/agent-knowledge.mdc` | Always-on rule: loads memory context on every session |
-| `.cursor/hooks.json` | Lifecycle hooks: sync on start, update on write, sync on stop and pre-compact |
-| `.cursor/commands/memory-update.md` | `/memory-update` slash command |
-| `.cursor/commands/system-update.md` | `/system-update` slash command |
-
-### Session lifecycle
-
-When you open the project in Cursor, the hooks fire automatically:
-
-- **session-start** — runs `agent-knowledge sync` to load fresh vault state
-- **post-write** — runs `agent-knowledge update` after each file save
-- **stop** — runs `agent-knowledge sync` at end of each task
-- **preCompact** — runs `agent-knowledge sync` before context compaction
-
-The rule 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 Cursor session in this project:
-
-- `/memory-update` — triggers a guided memory update flow: sync, review session work, write stable facts to `Memory/`, summarize
-- `/system-update` — refreshes the project's integration files to the latest framework version
-
-These are project-local commands. They work because `init` installed them in `.cursor/commands/`.
-
-### Checking integration health
-
-```bash
-agent-knowledge doctor
-```
-
-Reports whether rules, hooks, and commands are all installed and current. If any
-integration file is stale, `doctor` suggests `agent-knowledge refresh-system`.
 
 ## Multi-Tool Support
 
@@ -368,6 +337,7 @@ Common issues:
 - Onboarding still pending: paste the init prompt into your agent
 - Stale index: run `agent-knowledge index` or `agent-knowledge sync`
 - Large notes: run `agent-knowledge compact`
+- **Wrong binary**: another tool (e.g. graphify) may install a Node.js `agent-knowledge` that shadows ours. Check with `which -a agent-knowledge`. Fix: add the Python bin to PATH before nvm — `export PATH="$(python3 -c 'import sysconfig; print(sysconfig.get_path("scripts"))'):$PATH"` — or invoke directly: `python3 -m agent_knowledge`
 
 ## Platform Support
 

{agent_knowledge_cli-0.2.3 → agent_knowledge_cli-0.2.4}/README.md

@@ -8,24 +8,22 @@ just markdown files and a CLI.
 
 ## Install
 
-```
+```bash
 pip install agent-knowledge-cli
 ```
 
-This installs the `agent-knowledge` command. PyPI package name is `agent-knowledge-cli`;
-the CLI command and all documentation refer to it as `agent-knowledge`.
+PyPI package name: `agent-knowledge-cli`. CLI command and all docs: `agent-knowledge`.
 
 ## Quick Start
 
 ```bash
-pip install agent-knowledge-cli
 cd your-project
 agent-knowledge init
 ```
 
-Open Cursor in the repo — the agent picks up from there automatically.
+Open Cursor — the agent picks up from there automatically.
 
-`init` installs everything needed in the project:
+`init` does everything in one shot:
 - infers the project slug from the directory name
 - creates an external knowledge vault at `~/agent-os/projects/<slug>/`
 - symlinks `./agent-knowledge` into the repo as the local handle
@@ -34,46 +32,44 @@ Open Cursor in the repo — the agent picks up from there automatically.
 - installs `.cursor/commands/memory-update.md` and `system-update.md` — slash commands
 - detects Claude and Codex and installs their bridge files if present
 - bootstraps the memory tree and marks onboarding as `pending`
-- backfills lightweight history from git (if existing repo)
+- imports repo history into `Evidence/` automatically
+- backfills lightweight history from git
 
 ## How It Works
 
-```
-your-project/
-  .agent-project.yaml        # project config
-  AGENTS.md                   # instructions agents read on startup
-  agent-knowledge/            # symlink -> ~/agent-os/projects/<slug>/
-    STATUS.md                 # onboarding state + sync timestamps
-    Memory/                   # curated, durable knowledge (source of truth)
-      MEMORY.md
-      stack.md
-      decisions/
-        decisions.md
-    Evidence/                 # imported or extracted material (not canonical)
-      raw/
-      imports/
-      captures/               # automatic event stream
-    Outputs/                  # generated views (never canonical)
-      knowledge-index.json
-      knowledge-index.md
-      knowledge-export.html
-    Sessions/                 # ephemeral session state
-```
-
-Knowledge lives **outside** the repo so it persists across branches, tools,
-and clones. The symlink gives every tool a stable `./agent-knowledge` path.
+Knowledge lives **outside** the repo at `~/agent-os/projects/<slug>/` so it persists
+across branches, tools, and clones. The symlink `./agent-knowledge` gives every tool
+a stable local handle.
 
 ### Architecture boundaries
 
 | Folder | Role | Canonical? |
 |--------|------|-----------|
-| `Memory/` | Curated, durable facts -- source of truth | Yes |
+| `Memory/` | Curated, durable facts — source of truth | Yes |
+| `History/` | What happened over time — lightweight diary | Yes (diary) |
 | `Evidence/` | Imported/extracted material, event stream | No |
 | `Outputs/` | Generated views, indexes, HTML export | No |
 | `Sessions/` | Ephemeral session state, prune aggressively | No |
 
 Evidence is never auto-promoted into Memory. Outputs are never treated as truth.
-Only agents and humans deliberately write to Memory.
+Only agents and humans deliberately write to Memory or History.
+
+## 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.
+
+![Obsidian graph view of a project knowledge vault](docs/obsidian-graph.png)
+
+For a spatial canvas of the knowledge graph:
+
+```bash
+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.
 
 ### Automatic capture
 
@@ -96,33 +92,65 @@ on every sync. It provides a compact catalog of all notes so agents can:
 Use `agent-knowledge search <query>` to run a quick Layer 2 shortlist query
 from the command line or a hook.
 
-#
+## Cursor-first runtime
+
+Cursor is the primary supported runtime path. The project carries everything
+it needs — opening the repo in Cursor is enough to get automatic behavior:
+
+| What is installed | What it does |
+|------------------|-------------|
+| `.cursor/rules/agent-knowledge.mdc` | Always-on rule: loads memory context on every session |
+| `.cursor/hooks.json` | Lifecycle hooks: sync on start, update on write, sync on stop and pre-compact |
+| `.cursor/commands/memory-update.md` | `/memory-update` slash command |
+| `.cursor/commands/system-update.md` | `/system-update` slash command |
+
+### Session lifecycle
+
+When you open the project in Cursor, the hooks fire automatically:
+
+- **session-start** — runs `agent-knowledge sync` to load fresh vault state
+- **post-write** — runs `agent-knowledge update` after each file save
+- **stop** — runs `agent-knowledge sync` at end of each task
+- **preCompact** — runs `agent-knowledge sync` before context compaction
+
+The rule 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 Cursor session in this project:
+
+- `/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. They work because `init` installed them in `.cursor/commands/`.
+
+### Integration health
+
+```bash
+agent-knowledge doctor
+```
+
+Reports whether rules, hooks, and commands are all installed and current.
+If any file is stale or missing, `doctor` suggests `agent-knowledge refresh-system`.
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `init` | Set up a project (zero-arg, auto-detects everything) |
-| `sync` | Memory sync + session rollup + git evidence + capture + index |
-| `doctor` | Validate setup and report health |
-| `update` | Sync project changes into the knowledge tree |
-| `import` | Import repo history into Evidence/ |
-| `ship` | Validate, sync, commit, push |
-| `bootstrap` | Create or repair the memory tree |
-| `setup` | Install global Cursor rules and skills |
-| `global-sync` | Import safe local tooling config |
-| `graphify-sync` | Import graph/discovery artifacts |
-| `compact` | Prune stale memory and old captures |
-| `index` | Regenerate the knowledge index in Outputs/ |
+| `init` | Set up a project — one command, no arguments needed |
+| `sync` | Full sync: memory, history, git evidence, index |
+| `doctor` | Validate setup, integration health, version staleness |
+| `ship` | Validate + sync + commit + push |
 | `search <query>` | Search the knowledge index (Memory-first) |
-| `export-html` | Build polished static site in Outputs/site/ |
-| `view` | Build site and open it in the browser |
-| `clean-import <url>` | Import a URL or HTML file as cleaned evidence |
-| `refresh-system` | Refresh integration files to the current framework version |
-| `export-canvas` | Export vault as an Obsidian Canvas file (optional) |
-| `backfill-history` | Backfill lightweight project history from git |
-| `measure-tokens` | Estimate context token savings |
+| `export-html` | Build a polished static site from the vault |
+| `view` | Build site and open in browser |
+| `clean-import <url>` | Import a URL as cleaned, non-canonical evidence |
+| `refresh-system` | Refresh all integration files to the current framework version |
+| `backfill-history` | Rebuild lightweight project history from git |
+| `compact` | Prune stale captures and old session state |
 
-All write commands support `--dry-run`. Use `--json` for machine-readable output.
+All write commands support `--dry-run` and `--json`. Run `agent-knowledge --help` for the full command list.
 
 ## Static site export with graph
 
@@ -203,65 +231,6 @@ Strips navigation, ads, scripts, and boilerplate. Writes clean markdown with
 YAML frontmatter marking it as non-canonical. Verify facts before promoting
 any content to Memory/.
 
-## Obsidian (optional)
-
-Obsidian is an **optional** viewer/editor. agent-knowledge is not Obsidian-centric.
-
-Open `~/agent-os/projects/<slug>/` as an Obsidian vault for backlinks and graph view.
-
-![Obsidian graph view of a project knowledge vault](docs/obsidian-graph.png)
-
-For an optional spatial canvas of the knowledge graph:
-
-```
-agent-knowledge export-canvas
-# produces: agent-knowledge/Outputs/knowledge-export.canvas
-# open in Obsidian with Core plugins > Canvas
-```
-
-All Obsidian-specific features are optional. The system works fully without Obsidian.
-
-## Cursor-first runtime
-
-Cursor is the primary supported runtime path. The project carries everything
-it needs — opening the repo in Cursor is enough to get automatic behavior:
-
-| What is installed | What it does |
-|------------------|-------------|
-| `.cursor/rules/agent-knowledge.mdc` | Always-on rule: loads memory context on every session |
-| `.cursor/hooks.json` | Lifecycle hooks: sync on start, update on write, sync on stop and pre-compact |
-| `.cursor/commands/memory-update.md` | `/memory-update` slash command |
-| `.cursor/commands/system-update.md` | `/system-update` slash command |
-
-### Session lifecycle
-
-When you open the project in Cursor, the hooks fire automatically:
-
-- **session-start** — runs `agent-knowledge sync` to load fresh vault state
-- **post-write** — runs `agent-knowledge update` after each file save
-- **stop** — runs `agent-knowledge sync` at end of each task
-- **preCompact** — runs `agent-knowledge sync` before context compaction
-
-The rule 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 Cursor session in this project:
-
-- `/memory-update` — triggers a guided memory update flow: sync, review session work, write stable facts to `Memory/`, summarize
-- `/system-update` — refreshes the project's integration files to the latest framework version
-
-These are project-local commands. They work because `init` installed them in `.cursor/commands/`.
-
-### Checking integration health
-
-```bash
-agent-knowledge doctor
-```
-
-Reports whether rules, hooks, and commands are all installed and current. If any
-integration file is stale, `doctor` suggests `agent-knowledge refresh-system`.
 
 ## Multi-Tool Support
 
@@ -344,6 +313,7 @@ Common issues:
 - Onboarding still pending: paste the init prompt into your agent
 - Stale index: run `agent-knowledge index` or `agent-knowledge sync`
 - Large notes: run `agent-knowledge compact`
+- **Wrong binary**: another tool (e.g. graphify) may install a Node.js `agent-knowledge` that shadows ours. Check with `which -a agent-knowledge`. Fix: add the Python bin to PATH before nvm — `export PATH="$(python3 -c 'import sysconfig; print(sysconfig.get_path("scripts"))'):$PATH"` — or invoke directly: `python3 -m agent_knowledge`
 
 ## Platform Support
 

{agent_knowledge_cli-0.2.3 → agent_knowledge_cli-0.2.4}/src/agent_knowledge/__init__.py

@@ -1,3 +1,3 @@
 """agent-knowledge: adaptive, file-based project knowledge for AI coding agents."""
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"