agent-knowledge-cli 0.1.2__tar.gz

agent_knowledge_cli-0.1.2/.gitignore

@@ -0,0 +1,21 @@
+*.swp
+*.swo
+*~
+.DS_Store
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.whl
+.eggs/
+.venv/
+.pytest_cache/
+
+# Local project knowledge (created by agent-knowledge init on this repo)
+/agent-knowledge
+/.agent-project.yaml
+/.agentknowledgeignore
+/AGENTS.md
+/CLAUDE.md
+/.cursor/hooks.json

agent_knowledge_cli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-knowledge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_knowledge_cli-0.1.2/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: agent-knowledge-cli
+Version: 0.1.2
+Summary: Adaptive, file-based project knowledge for AI coding agents
+Author: agent-knowledge contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: tokens
+Requires-Dist: tiktoken; extra == 'tokens'
+Description-Content-Type: text/markdown
+
+# 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.
+
+## Install
+
+```
+pip install agent-knowledge-cli
+```
+
+## Quick Start
+
+```
+cd your-project
+agent-knowledge init
+```
+
+Open Cursor, Claude, or Codex in the repo -- the agent picks up from there.
+
+`init` automatically:
+- 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
+- detects Cursor, Claude, and Codex and installs integration files
+- bootstraps the memory tree and marks onboarding as `pending`
+- prints the prompt to kick off first-time agent ingestion
+
+## 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/
+      MEMORY.md              # root entrypoint (read first)
+      stack.md               # flat branch note
+      perception/
+        perception.md        # branch entry (same name as folder)
+        fusion.md            # subtopic note
+      decisions/
+        decisions.md         # decision log
+    Evidence/                # imported/extracted material
+    Outputs/                 # generated views (never canonical)
+    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.
+
+When an agent opens the repo it reads `AGENTS.md` and `STATUS.md`.
+If onboarding is pending, it inspects the project, imports evidence,
+infers the ontology from the actual repo, and writes curated memory.
+After that, maintenance is automatic.
+
+## Branch Convention
+
+The memory tree uses a same-name branch-note convention:
+
+- **Flat note** (`stack.md`): for topics with no subtopics
+- **Folder** (`perception/perception.md`): for topics that grow subtopics
+- **Folder name = topic**, entry note = same name as folder
+- **Agents infer** the branch structure from the real project -- no fixed profiles
+
+The agent starts small (2-4 branches) and grows the tree only when justified.
+Hooks stay thin -- they detect changes and trigger updates, not rebuild the ontology.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `init` | Set up a project (zero-arg, auto-detects everything) |
+| `sync` | Push memory updates + extract git evidence |
+| `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 |
+| `setup` | Install global Cursor rules and skills |
+| `global-sync` | Import safe local tooling config |
+| `measure-tokens` | Estimate context token savings |
+
+All write commands support `--dry-run`. Use `--json` for machine-readable output.
+
+## Multi-Tool Support
+
+`init` detects which tools are present and installs the right bridge files:
+
+| Tool | Bridge file | When installed |
+|------|-------------|---------------|
+| Cursor | `.cursor/hooks.json` + `.cursor/rules/agent-knowledge.mdc` | Always (hooks/rules are inert outside Cursor) |
+| Claude | `CLAUDE.md` | When `.claude/` directory is detected |
+| Codex | `.codex/AGENTS.md` | When `.codex/` directory is detected |
+
+Multiple tools in the same repo work together.
+
+## Obsidian
+
+Open `~/agent-os/projects/<slug>/` as an Obsidian vault. The knowledge graph
+shows all memory areas, evidence, and dashboards connected through wiki-links.
+
+Enable **Graph view** in Settings > Core plugins and set
+**Files and links > Use `[[Wikilinks]]`** to ON for the best experience.
+
+## Custom Knowledge Home
+
+```bash
+export AGENT_KNOWLEDGE_HOME=~/my-knowledge
+agent-knowledge init
+```
+
+## Platform Support
+
+- **macOS** and **Linux** are fully supported.
+- **Windows** is not currently supported. The CLI relies on `bash` and POSIX shell
+  scripts for most operations.
+- Python 3.9+ is required.
+
+## Development
+
+```bash
+git clone <repo-url>
+cd agent-knowledge
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest tests/ -q
+```

agent_knowledge_cli-0.1.2/README.md

@@ -0,0 +1,131 @@
+# 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.
+
+## Install
+
+```
+pip install agent-knowledge-cli
+```
+
+## Quick Start
+
+```
+cd your-project
+agent-knowledge init
+```
+
+Open Cursor, Claude, or Codex in the repo -- the agent picks up from there.
+
+`init` automatically:
+- 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
+- detects Cursor, Claude, and Codex and installs integration files
+- bootstraps the memory tree and marks onboarding as `pending`
+- prints the prompt to kick off first-time agent ingestion
+
+## 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/
+      MEMORY.md              # root entrypoint (read first)
+      stack.md               # flat branch note
+      perception/
+        perception.md        # branch entry (same name as folder)
+        fusion.md            # subtopic note
+      decisions/
+        decisions.md         # decision log
+    Evidence/                # imported/extracted material
+    Outputs/                 # generated views (never canonical)
+    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.
+
+When an agent opens the repo it reads `AGENTS.md` and `STATUS.md`.
+If onboarding is pending, it inspects the project, imports evidence,
+infers the ontology from the actual repo, and writes curated memory.
+After that, maintenance is automatic.
+
+## Branch Convention
+
+The memory tree uses a same-name branch-note convention:
+
+- **Flat note** (`stack.md`): for topics with no subtopics
+- **Folder** (`perception/perception.md`): for topics that grow subtopics
+- **Folder name = topic**, entry note = same name as folder
+- **Agents infer** the branch structure from the real project -- no fixed profiles
+
+The agent starts small (2-4 branches) and grows the tree only when justified.
+Hooks stay thin -- they detect changes and trigger updates, not rebuild the ontology.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `init` | Set up a project (zero-arg, auto-detects everything) |
+| `sync` | Push memory updates + extract git evidence |
+| `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 |
+| `setup` | Install global Cursor rules and skills |
+| `global-sync` | Import safe local tooling config |
+| `measure-tokens` | Estimate context token savings |
+
+All write commands support `--dry-run`. Use `--json` for machine-readable output.
+
+## Multi-Tool Support
+
+`init` detects which tools are present and installs the right bridge files:
+
+| Tool | Bridge file | When installed |
+|------|-------------|---------------|
+| Cursor | `.cursor/hooks.json` + `.cursor/rules/agent-knowledge.mdc` | Always (hooks/rules are inert outside Cursor) |
+| Claude | `CLAUDE.md` | When `.claude/` directory is detected |
+| Codex | `.codex/AGENTS.md` | When `.codex/` directory is detected |
+
+Multiple tools in the same repo work together.
+
+## Obsidian
+
+Open `~/agent-os/projects/<slug>/` as an Obsidian vault. The knowledge graph
+shows all memory areas, evidence, and dashboards connected through wiki-links.
+
+Enable **Graph view** in Settings > Core plugins and set
+**Files and links > Use `[[Wikilinks]]`** to ON for the best experience.
+
+## Custom Knowledge Home
+
+```bash
+export AGENT_KNOWLEDGE_HOME=~/my-knowledge
+agent-knowledge init
+```
+
+## Platform Support
+
+- **macOS** and **Linux** are fully supported.
+- **Windows** is not currently supported. The CLI relies on `bash` and POSIX shell
+  scripts for most operations.
+- Python 3.9+ is required.
+
+## Development
+
+```bash
+git clone <repo-url>
+cd agent-knowledge
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest tests/ -q
+```

agent_knowledge_cli-0.1.2/assets/claude/global.md

@@ -0,0 +1,44 @@
+# AI Assistant Global Rules
+
+## Communication Style
+
+Think deeply, act decisively, speak briefly.
+
+- Execute over explain — let code and results speak
+- Lead with the action or answer, not the reasoning
+- No preambles, filler text, or summaries of what was just done
+- Only detailed explanations when explicitly requested
+- Short, direct sentences over long explanations
+
+## Prohibitions
+
+- No emojis or icons in code, logs, or responses — plain text only
+- Never create .md, README, CHANGELOG, or documentation files unless explicitly asked
+  - Exception: internal memory/session files are fine to create and update freely
+
+## Workflow
+
+- Plan before any non-trivial task (3+ steps or architectural decisions)
+- Use subagents liberally to keep the main context window clean and for parallel work
+- After any user correction: record the pattern to prevent repeating it
+- Never mark a task complete without proving it works
+- For non-trivial changes: ask "is there a more elegant way?" before presenting
+- When given a bug report: fix it autonomously — no hand-holding needed
+- When the user describes a constraint or says something won't work: stop and accept it. One confirmation attempt max — do not re-discover what the user already knows
+
+## Code Quality
+
+- Simplicity first: make every change as simple as possible, impact minimal code
+- No laziness: find root causes, no temporary fixes, senior developer standards
+- Minimal impact: only touch what is necessary, avoid introducing bugs
+- No ORMs unless the project already uses one
+- No new dependencies without asking first
+
+## Memory
+
+- Save stable patterns, preferences, and architectural decisions to memory files
+- Keep the Memory/MEMORY.md note concise (truncated after ~200 lines); put detail in branch files
+- Update or remove memories that turn out to be wrong or outdated
+- Never save session-specific, in-progress, or speculative information
+- When the user asks to remember something: save it immediately
+- When the user asks to forget something: remove it immediately

agent_knowledge_cli-0.1.2/assets/claude/project-template.md

@@ -0,0 +1,46 @@
+# Project: <Name>
+
+<!-- Drop this file at the project root as CLAUDE.md -->
+<!-- It is read automatically by Claude Code at the start of every session -->
+<!-- Global rules in ~/.claude/CLAUDE.md are also loaded — no need to repeat them here -->
+
+## Stack
+
+- <language/runtime>
+- <framework>
+- <database>
+- <key libraries>
+
+## Key Directories
+
+- `src/` — <description>
+- `tests/` — <description>
+
+## Conventions
+
+- <naming conventions>
+- <patterns to follow>
+- <patterns to avoid>
+
+## What NOT to do
+
+- Do not install <X> — we use <Y> instead
+- Do not restructure <X> without asking
+- Do not commit secrets — use .env.template as reference
+
+## When unsure
+
+- Search the codebase first. Reuse existing patterns.
+- Ask before creating new packages or major abstractions.
+- Read docs in `docs/` or `agent-knowledge/` before implementing.
+
+## Shared Memory
+
+Persistent project memory lives at `agent-knowledge/Memory/MEMORY.md`.
+The local `agent-knowledge/` path should point to the real dedicated knowledge folder.
+Read it at the start of each session. Write back after meaningful changes.
+
+- If `agent-knowledge/Memory/MEMORY.md` is missing: run `scripts/bootstrap-memory-tree.sh .`
+- After any architectural decision: use the `decision-recording` skill
+- After any meaningful state change: follow the `memory-writeback` rule
+- To backfill from git/docs history: run `scripts/import-agent-history.sh .`

agent_knowledge_cli-0.1.2/assets/claude/scripts/install.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+#
+# Install Claude Code global rules into ~/.claude/CLAUDE.md
+#
+# Usage:
+#   ./install.sh              # install global rules
+#   ./install.sh /path/to/project  # also install project template into project root
+#
+# The global rules are appended under a managed section marker so re-running
+# this script is safe (it replaces the section, not appends again).
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLAUDE_DIR="$HOME/.claude"
+GLOBAL_SOURCE="$SCRIPT_DIR/../global.md"
+GLOBAL_TARGET="$CLAUDE_DIR/CLAUDE.md"
+PROJECT="${1:-}"
+
+MARKER_START="<!-- agents-rules:global:start -->"
+MARKER_END="<!-- agents-rules:global:end -->"
+
+mkdir -p "$CLAUDE_DIR"
+
+install_global() {
+    local content
+    content="$(cat "$GLOBAL_SOURCE")"
+
+    if [ -f "$GLOBAL_TARGET" ]; then
+        # Remove existing managed section if present
+        if grep -q "$MARKER_START" "$GLOBAL_TARGET" 2>/dev/null; then
+            # Strip from marker-start to marker-end inclusive
+            local tmp
+            tmp="$(mktemp)"
+            awk "/$MARKER_START/{flag=1} !flag{print} /$MARKER_END/{flag=0}" "$GLOBAL_TARGET" > "$tmp"
+            mv "$tmp" "$GLOBAL_TARGET"
+            echo "  updated existing section in $GLOBAL_TARGET"
+        else
+            echo "  appending to existing $GLOBAL_TARGET"
+            echo "" >> "$GLOBAL_TARGET"
+        fi
+    else
+        echo "  creating $GLOBAL_TARGET"
+    fi
+
+    {
+        echo "$MARKER_START"
+        echo "$content"
+        echo "$MARKER_END"
+    } >> "$GLOBAL_TARGET"
+
+    echo "  global rules installed -> $GLOBAL_TARGET"
+}
+
+install_project_template() {
+    local project_dir
+    project_dir="$(cd "$1" && pwd)"
+    local target="$project_dir/CLAUDE.md"
+    local source="$SCRIPT_DIR/../project-template.md"
+
+    if [ -f "$target" ]; then
+        echo "  $target already exists — skipping (edit manually)"
+    else
+        cp "$source" "$target"
+        echo "  project template installed -> $target"
+        echo "  Edit CLAUDE.md with your project-specific rules"
+    fi
+}
+
+echo "Installing Claude Code rules..."
+echo ""
+
+install_global
+
+if [ -n "$PROJECT" ]; then
+    install_project_template "$PROJECT"
+fi
+
+echo ""
+echo "Done."
+echo ""
+echo "Claude Code reads:"
+echo "  ~/.claude/CLAUDE.md         <- global rules (all projects)"
+echo "  <project>/CLAUDE.md         <- project rules (this project only)"

agent_knowledge_cli-0.1.2/assets/commands/doctor.md

@@ -0,0 +1,21 @@
+# Doctor
+
+Doctor is the quick troubleshooting entrypoint for a connected project knowledge setup.
+
+## Behavior
+
+- run knowledge validation
+- verify the local `./agent-knowledge` pointer and external source-of-truth path
+- check project setup files such as `.agent-project.yaml`, `AGENTS.md`, and optional repo-local hooks
+- summarize health warnings and the current operational state
+
+## Safety
+
+- read-mostly command
+- may refresh `agent-knowledge/STATUS.md` unless `--dry-run` is used
+
+## Expected Script Entry Point
+
+```bash
+scripts/doctor.sh --project /path/to/project
+```

agent_knowledge_cli-0.1.2/assets/commands/global-knowledge-sync.md

@@ -0,0 +1,27 @@
+# Global Knowledge Sync
+
+Global knowledge sync builds a project-scoped tooling knowledge view from safe,
+allowlisted user-level tool surfaces. It still writes through `./agent-knowledge`,
+which should resolve to the external project knowledge folder.
+
+## Behavior
+
+- scan allowlisted local configuration sources such as `~/.claude/`, `~/.codex/`, and optional safe Cursor customizations
+- skip opaque caches, auth/session surfaces, and suspicious secret-bearing files
+- redact sensitive lines before writing evidence
+- write redacted imports under `agent-knowledge/Evidence/tooling/`
+- write curated summaries under `agent-knowledge/Memory/tooling/`
+- update `agent-knowledge/STATUS.md`
+
+## Safety
+
+- use `--dry-run` to preview writes
+- reruns should be idempotent
+- summaries must report both scanned sources and safety skips
+
+## Expected Script Entry Point
+
+```bash
+scripts/global-knowledge-sync.sh --project /path/to/project
+scripts/global-knowledge-sync.sh --project /path/to/project --dry-run
+```

agent_knowledge_cli-0.1.2/assets/commands/graphify-sync.md

@@ -0,0 +1,26 @@
+# Graphify Sync
+
+Graphify sync is the optional structural-discovery import flow for graph-style project exports.
+It writes through `./agent-knowledge`, but keeps imported graph structure in `Evidence/` and `Outputs/`, not in durable memory.
+
+## Behavior
+
+- detect whether `graphify` or equivalent structural export artifacts are available
+- import safe graph/report/json artifacts into `agent-knowledge/Evidence/imports/graphify/`
+- generate concise structural summaries under `agent-knowledge/Outputs/graphify/`
+- tag imported material with confidence metadata such as `EXTRACTED` or `INFERRED`
+- summarize what was imported, what was cached, and what was skipped
+
+## Safety
+
+- optional only; missing graph tooling must not fail the project knowledge system
+- use `--dry-run` to preview all writes
+- imported graph outputs are evidence first and are not promoted into `Memory/` automatically
+
+## Expected Script Entry Point
+
+```bash
+scripts/graphify-sync.sh --project /path/to/project
+scripts/graphify-sync.sh --project /path/to/project --source /path/to/graphify-export
+scripts/graphify-sync.sh --project /path/to/project --dry-run
+```

agent_knowledge_cli-0.1.2/assets/commands/knowledge-sync.md

@@ -0,0 +1,26 @@
+# Knowledge Sync
+
+Knowledge sync is the connected-project maintenance flow for the adaptive memory system. It writes through `./agent-knowledge`, which should resolve to the external project knowledge folder.
+
+## Behavior
+
+- inspect current repo changes
+- classify touched files into the relevant `agent-knowledge/Memory/` branch notes
+- append durable recent-change entries when knowledge meaningfully changed
+- optionally record a decision note when explicitly requested
+- refresh raw and imported evidence without treating it as curated truth
+- update `agent-knowledge/STATUS.md`
+
+## Safety
+
+- use `--dry-run` to preview all file writes
+- idempotent reruns should not duplicate recent-change bullets
+- sessions and evidence stay separate from durable memory
+
+## Expected Script Entry Point
+
+```bash
+scripts/update-knowledge.sh --project /path/to/project
+scripts/update-knowledge.sh --project /path/to/project --decision-title "Adopt X"
+scripts/update-knowledge.sh --project /path/to/project --dry-run
+```

agent_knowledge_cli-0.1.2/assets/commands/ship.md

@@ -0,0 +1,29 @@
+# Ship
+
+Ship is the operational release-prep flow for a connected project repo.
+
+## Behavior
+
+- inspect git status and current branch
+- refuse to continue on detached HEAD or merge conflicts
+- run detected validation commands for the repo
+- run knowledge sync and compaction before commit
+- stage repo-local changes
+- generate or accept a concise commit message
+- commit and push when possible
+- optionally open a PR when requested
+
+## Safety
+
+- use `--dry-run` to preview validations, git actions, and knowledge updates
+- knowledge updates still run through `./agent-knowledge`; the script does not convert the system into repo-local storage
+- if the real knowledge vault lives outside the repo, the script reports that instead of pretending to stage it
+- reruns are no-op when nothing changed
+
+## Expected Script Entry Point
+
+```bash
+scripts/ship.sh --project /path/to/project
+scripts/ship.sh --project /path/to/project --message "chore: ship update"
+scripts/ship.sh --project /path/to/project --open-pr --dry-run
+```