agent-knowledge-cli 0.1.2__py3-none-any.whl

agent_knowledge/__init__.py

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

agent_knowledge/__main__.py

@@ -0,0 +1,3 @@
+from agent_knowledge.cli import main
+
+main()

agent_knowledge/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/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/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/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/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/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/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/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
+```

agent_knowledge/assets/rules/generate-architecture-doc.mdc

@@ -0,0 +1,87 @@
+---
+description: Generate an architecture HTML document for a Cramim ROS2 package. Use when asked to create architecture docs, explain a package, or document a node's behavior.
+globs: 
+alwaysApply: false
+---
+
+# Generate Architecture HTML Document
+
+When asked to create an architecture document for a Cramim package, produce a self-contained HTML file in `architecture_docs/` following this process.
+
+## 1. Research the Package
+
+Before writing anything, thoroughly investigate the target package:
+
+- Read all `.hpp` and `.cpp` files in the package
+- Read `package.xml` and `CMakeLists.txt` for dependencies
+- Read any config/YAML files referenced by launch files
+- Grep for `create_publisher`, `create_subscription`, `create_service`, `create_client` to find all ROS interfaces
+- Grep for state definitions (`State::createStateSharedPtr`, enums, or equivalent patterns)
+- Trace the full data flow from inputs to outputs
+- Identify all inter-node communication patterns
+- Read launch files to understand how the node is started and configured
+
+## 2. Required Content Sections
+
+Every architecture doc must include:
+
+1. **Executive summary** — what the component does, 2-3 sentences, with role badges for related components
+2. **Table of contents** with anchor links
+3. **Architecture diagram** — where this component fits in the overall Cramim system (Mermaid flowchart)
+4. **State machine** (if applicable) — Mermaid `stateDiagram-v2` with all states and transitions
+5. **State details** — `on_enter`, `in_state`, `on_exit` callbacks for each state (table per state)
+6. **Transition table** — every transition with From, To, Condition, Side Effect columns
+7. **End-to-end flow** — Mermaid `sequenceDiagram` showing the main operational flow
+8. **Topics & services** — tables for published topics, subscribed topics, provided services, called services (columns: name, type, description)
+9. **Interactions with other nodes** — summary cards showing who talks to whom
+10. **Key design decisions** — bullet list of architectural choices and why
+11. **File structure** — annotated directory tree in a `<pre>` block
+
+## 3. Visual Style
+
+Use the exact dark-theme style from the reference file `architecture_docs/dc_behavior_tree_workplan.html`:
+
+- **Mermaid**: CDN `mermaid@10.6.1`, dark theme with custom `themeVariables`
+- **Font**: `JetBrains Mono`, `Fira Code`, `Consolas`, monospace
+- **Background**: `#0a0e14` → `#151d28` gradient
+- **CSS variables**: `--accent-cyan: #39c5cf`, `--accent-green: #7fdb57`, `--accent-yellow: #ffcc66`, `--accent-orange: #ff8f40`, `--accent-red: #ff6b6b`, `--accent-purple: #c792ea`, `--accent-blue: #82aaff`
+- **Cards**: `.description` boxes with `.highlight-{color}` left borders
+- **Grids**: `.summary-grid` / `.summary-card` for card layouts
+- **Flows**: `.flow-box` with numbered circles for sequential steps
+- **Tables**: gradient header (`cyan → purple`), hover highlight, uppercase headers
+- **Section headers**: centered `h2` with emoji prefix
+- **Responsive**: `@media (max-width: 768px)` breakpoint
+
+## 4. Mermaid Configuration
+
+Always include this exact mermaid init block at the bottom of the HTML:
+
+```javascript
+mermaid.initialize({
+    startOnLoad: true,
+    theme: 'dark',
+    themeVariables: {
+        primaryColor: '#39c5cf',
+        primaryTextColor: '#e6edf3',
+        primaryBorderColor: '#39c5cf',
+        lineColor: '#82aaff',
+        secondaryColor: '#2d3a4a',
+        tertiaryColor: '#1a2433',
+        background: '#1a2433',
+        mainBkg: '#1a2433',
+        nodeBorder: '#2d3a4a',
+        clusterBkg: '#151d28',
+        clusterBorder: '#2d3a4a',
+        titleColor: '#39c5cf',
+        edgeLabelBackground: '#1a2433'
+    },
+    flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis', padding: 15 },
+    sequence: { useMaxWidth: true, mirrorActors: false, bottomMarginAdj: 1 }
+});
+```
+
+## 5. Output
+
+- Save to `architecture_docs/{package_name}_architecture.html`
+- File must be fully self-contained (no external CSS, only CDN JS for mermaid)
+- Open in any browser without a server

agent_knowledge/assets/rules/history-backfill.mdc

@@ -0,0 +1,67 @@
+---
+description: When onboarding an existing project, perform history backfill before normal steady-state memory maintenance.
+alwaysApply: false
+---
+
+# History Backfill
+
+After bootstrapping memory on a project with existing history, backfill the memory tree
+from evidence before proceeding with steady-state work.
+
+Apply this rule once per project. It is not needed on every session.
+
+---
+
+## When to apply
+
+Apply after `memory-bootstrap` when the project:
+- Has a git history with more than ~10 commits
+- Has existing documentation (README, CLAUDE.md, AGENTS.md, `.agent-project.yaml`, `agent-knowledge/`)
+- Has existing task files (`tasks/todo.md`, `tasks/lessons.md`)
+- Was previously worked on by another agent or developer
+
+Do NOT apply on every session — only when onboarding or when memory is newly empty.
+
+---
+
+## Steps (summary — full detail in skill)
+
+1. Read the `history-backfill` skill.
+2. Run `scripts/import-agent-history.sh .` to collect raw evidence.
+3. Read evidence files in priority order (docs first, then manifests/configs/tests/workflows, then git and sessions).
+4. Distill stable facts into memory branch notes (Current State section).
+5. Record any architectural decisions found in `decisions/`.
+6. Update `Memory/MEMORY.md` branch summaries to reflect real content.
+7. Leave Open Questions for anything evidence hints at but doesn't resolve.
+
+---
+
+## Evidence sources (priority order)
+
+1. `agent-knowledge/Evidence/imports/existing-docs.txt` — README, CLAUDE.md, AGENTS.md, `.agent-project.yaml`
+2. `agent-knowledge/Evidence/raw/manifests.txt` — authoritative for stack
+3. `agent-knowledge/Evidence/raw/config-files.txt` — strong signal for conventions
+4. `agent-knowledge/Evidence/raw/tests.txt` and `raw/ci-workflows.txt` — verification and deploy signal
+5. `agent-knowledge/Evidence/raw/structure.txt` — actual architecture shape
+6. `agent-knowledge/Evidence/imports/tasks.txt` and `imports/session-files.txt` — context and recurring work areas
+7. `agent-knowledge/Evidence/raw/git-log-detail.txt` and `raw/git-log.txt` — why and what changed over time
+8. `agent-knowledge/Evidence/imports/trace-index.txt` — supporting traces only, never canonical truth
+
+---
+
+## Separation principle
+
+Evidence (`agent-knowledge/Evidence/raw/` and `agent-knowledge/Evidence/imports/`) is input — overwritten or refreshed on each import run.
+Memory (`agent-knowledge/Memory/`) is curated output — maintained by the writeback rule.
+
+Never write evidence files into memory. Never treat a single evidence source as truth
+without corroboration.
+
+---
+
+## After backfill
+
+Switch to normal steady-state operation:
+- Apply `memory-writeback` rule after each meaningful task
+- Apply `memory-compaction` skill when files grow large
+- Do NOT re-run history backfill unless memory is reset or significantly corrupted

agent_knowledge/assets/rules/memory-bootstrap.mdc

@@ -0,0 +1,53 @@
+---
+description: If the project memory tree is missing or obviously generic, bootstrap it before starting heavy work.
+alwaysApply: true
+---
+
+# Memory Bootstrap
+
+Check for a valid memory tree at the start of any session that involves real project work.
+If missing, overly generic, or obviously stale, bootstrap it first.
+
+---
+
+## Check condition
+
+Look for `agent-knowledge/Memory/MEMORY.md` in the project root.
+The local `./agent-knowledge` path is the project entrypoint and should point to the real dedicated knowledge folder.
+
+| State | Action |
+|-------|--------|
+| File exists and has real content (not just template placeholders) | Skip -- proceed with the task |
+| File exists but contains only bootstrap placeholders or generic text | Re-bootstrap or backfill: read `project-ontology-bootstrap` skill |
+| File is missing, empty, or the `agent-knowledge` pointer is broken | Bootstrap: read `project-ontology-bootstrap` skill |
+
+"Real content" means the memory root has frontmatter and at least one branch note contains verified facts in **Current State**.
+
+---
+
+## Bootstrap steps (summary -- full detail in skill)
+
+1. Read the `project-ontology-bootstrap` skill.
+2. Ensure the local `./agent-knowledge` pointer exists and resolves to the external knowledge folder. If it does not, run `scripts/install-project-links.sh` first.
+3. Run `scripts/bootstrap-memory-tree.sh .` to create the minimal scaffold.
+4. Inspect repo structure, manifests, docs, configs, tests, and workflows.
+5. Infer the project ontology and create 2-4 initial branch notes using the project's own terminology.
+6. Use the same-name branch convention: `<topic>.md` for flat notes, `<topic>/<topic>.md` for branches with subtopics.
+7. Collect evidence with `scripts/import-agent-history.sh .`
+8. If the project already has history, apply `history-backfill`.
+9. Confirm the tree is in place before proceeding with the user's task.
+
+---
+
+## When to skip
+
+- Memory tree exists with real content -- always skip, do not re-bootstrap
+- User explicitly asked to skip bootstrap -- skip for this session only
+- The task is purely read-only exploration -- bootstrap is optional (do it anyway if convenient)
+
+---
+
+## After bootstrap
+
+Apply the `history-backfill` rule if the project has existing history (git log, docs, sessions).
+Then proceed with the user's task, applying the `memory-writeback` rule as work proceeds.

agent_knowledge/assets/rules/memory-writeback.mdc

@@ -0,0 +1,90 @@
+---
+description: After meaningful project state changes, update the correct memory branch -- or explicitly state no update is needed.
+alwaysApply: true
+---
+
+# Memory Writeback
+
+After any meaningful project change, evaluate whether durable project understanding changed.
+If yes, update the correct memory branch before ending the session.
+If no, say so explicitly.
+
+---
+
+## Evaluation -- ask after every meaningful task
+
+> "Did this session change what future sessions should understand about this project?"
+
+Write to memory if the answer is yes for any of:
+- An architectural decision was made or reversed
+- A new pattern or convention was confirmed
+- A critical gotcha was discovered (build, DB, API, environment, path)
+- A feature area was substantially completed or its design changed
+- A recurring mistake was corrected (record the lesson)
+- A dependency or external constraint changed
+
+Skip writeback if:
+- The session was read-only exploration with no new conclusions
+- The change is already captured in git or inline documentation
+- The fact is session-specific and won't matter in a future session
+- The fact is speculative and not yet confirmed
+- The work changed code but not project understanding
+
+When skipping, state it: **Memory writeback: none needed.**
+
+---
+
+## What to write and where
+
+| Fact type | Target |
+|-----------|--------|
+| Architectural decision | `Memory/decisions/YYYY-MM-DD-slug.md` + link from the relevant branch |
+| New pattern or convention | relevant branch note -> Current State |
+| Gotcha or constraint | relevant branch note -> Current State |
+| Stack change | relevant branch note -> Current State + Recent Changes |
+| Completed feature area | relevant branch note -> Current State |
+| Lesson from a mistake | relevant branch note -> Current State, with **Why:** and **How to apply:** |
+
+If no existing branch fits the fact, create a new branch note using the same-name convention.
+Use the project's own terminology for branch names.
+
+---
+
+## How to write
+
+1. Identify the target branch note.
+2. Read its current content.
+3. Preserve YAML frontmatter and add or update the fact in the correct section.
+   - **Current State**: what is true now (replace stale entries, don't append duplicates)
+   - **Recent Changes**: YYYY-MM-DD -- what changed (prune entries older than ~4 weeks)
+   - **Decisions**: link to decision file
+   - **Open Questions**: add unresolved items only if they remain open after verification
+4. If the branch now exceeds ~150 lines, follow the `memory-compaction` skill.
+5. If branch summaries changed, update `agent-knowledge/Memory/MEMORY.md`.
+
+For architectural decisions, use the `decision-recording` skill -- do not inline them.
+
+---
+
+## Format
+
+Lead with the fact:
+```
+Raw SQL + pgtyped types for all DB access. No ORM.
+```
+
+For lessons, add context:
+```
+Yarn is not in PATH on this machine -- use node .yarn/releases/yarn-4.x.cjs directly.
+Why: the repo uses Yarn 4 via Corepack, not the global yarn binary.
+How to apply: always invoke yarn via the release script, never via yarn directly.
+```
+
+---
+
+## Composability
+
+- Uses `memory-management` skill for file locations and structure
+- Uses `decision-recording` skill for architecture decisions
+- Uses `memory-compaction` skill when files grow large
+- Feeds from the `session-management` writeback gate