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

agent_knowledge/assets/templates/project/AGENTS.md

@@ -0,0 +1,87 @@
+# Agent Knowledge: <project-name>
+
+This project uses **agent-knowledge** for persistent project memory.
+All knowledge is accessed through `./agent-knowledge/` (symlink to external vault).
+
+## First-Time Onboarding
+
+Check `./agent-knowledge/STATUS.md`. If `onboarding: pending`:
+
+1. Inspect project structure: manifests, package files, CI/CD config, docs
+2. Inspect project-local tool config: `.cursor/`, `.claude/`, `.codex/` if present
+3. Review recent git history (last ~50 commits, key branches)
+4. Import findings into `Evidence/raw/` using `agent-knowledge import`
+5. Infer the project ontology from the actual repo -- use the project's own
+   functional domains as branch names (e.g., perception, navigation, localization),
+   not generic categories (e.g., architecture, conventions)
+6. Create one branch note per functional domain. Each note should be focused
+   and under ~150 lines. Do NOT put the whole system description in one file.
+7. Link related notes to each other with relative markdown links
+8. Update `Memory/MEMORY.md` with links to all new branches
+9. Update `./agent-knowledge/STATUS.md`: set `onboarding: complete`
+
+## Branch Convention
+
+Use the same-name branch-note pattern:
+
+```
+Memory/
+  MEMORY.md                    # root -- always read first
+  stack.md                     # flat note when no subtopics needed
+  perception/
+    perception.md              # entry note = same name as folder
+    fusion.md                  # subtopic note
+    lane-detection.md
+  navigation/
+    navigation.md
+    path-following.md
+  localization/
+    localization.md
+  decisions/
+    decisions.md               # decision log
+    2025-01-15-use-raw-sql.md  # individual decision
+```
+
+Rules:
+- Each branch = one focused functional domain from the project
+- Use the project's own terminology, not generic templates
+- Each note stays under ~150 lines. If a topic is too big, split it.
+- Link between related notes with relative markdown links (e.g.,
+  `See [perception](perception/perception.md) for sensor details`)
+- Small topic with no subtopics: one flat note (`stack.md`)
+- Bigger topic: folder + same-name entry note (`perception/perception.md`)
+- Do not create deep trees automatically -- grow only when justified
+- Do NOT lump unrelated subsystems into a single "architecture" note.
+  Split by functional domain instead.
+
+## Onboarding Rules
+
+- Only write confirmed facts to `Memory/` -- never speculate
+- Keep raw/extracted material in `Evidence/`, not `Memory/`
+- Keep generated views in `Outputs/` -- never treat as canonical truth
+- Do NOT redo onboarding if STATUS.md already shows `onboarding: complete`
+
+## Ongoing Maintenance
+
+After onboarding is complete, during normal work:
+- Update `Memory/` when stable facts change (decisions, conventions, gotchas)
+- Record architectural decisions in `Memory/decisions/`
+- Run `agent-knowledge update` after significant changes
+- Keep `Evidence/` and `Outputs/` separate from `Memory/`
+- Do NOT rebuild the knowledge tree every session
+
+## Knowledge Structure
+
+- `Memory/` -- Curated, durable project knowledge (source of truth)
+- `Evidence/` -- Imported/extracted material (not curated truth)
+- `Outputs/` -- Generated helper views (never canonical)
+- `Sessions/` -- Temporary session state (prune aggressively)
+- `STATUS.md` -- Onboarding and maintenance state
+- `.agent-project.yaml` -- Project configuration
+
+## Reading Order
+
+1. `Memory/MEMORY.md` -- always read first
+2. Relevant branch entry notes (e.g., `perception/perception.md`)
+3. Leaf notes only if the specific detail is needed
+4. Keep context lean -- do not read branches unrelated to the current task

agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/README.md

@@ -0,0 +1,23 @@
+---
+note_type: obsidian-index
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - obsidian
+---
+
+# .obsidian
+
+This starter setup keeps the vault markdown-first and portable.
+
+Open either:
+
+- the real external folder directly
+- or the local repo handle at `./agent-knowledge`
+
+Both should resolve to the same project knowledge vault.
+
+Keep this lightweight in shared repos.
+Avoid committing machine-specific workspace noise unless the team explicitly wants it.

agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/app.json

@@ -0,0 +1,5 @@
+{
+  "useMarkdownLinks": true,
+  "newLinkFormat": "relative",
+  "alwaysUpdateLinks": true
+}

agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/core-plugins.json

@@ -0,0 +1,7 @@
+[
+  "file-explorer",
+  "search",
+  "backlink",
+  "outgoing-link",
+  "tag-pane"
+]

agent_knowledge/assets/templates/project/agent-knowledge/Evidence/README.md

@@ -0,0 +1,34 @@
+---
+note_type: evidence-index
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - evidence
+---
+
+# Evidence
+
+Evidence is input for judgment, not canonical truth.
+
+## Raw
+
+Automatically collected snapshots from the current repo.
+→ [raw/README.md](raw/README.md)
+
+## Imports
+
+Imported docs, tasks, sessions, traces, and other supplemental artifacts.
+→ [imports/README.md](imports/README.md)
+
+## Tooling
+
+Optional redacted tooling imports created by the global tooling sync flow.
+→ `tooling/`
+
+## Confidence Labels
+
+- `EXTRACTED` means directly copied or listed from a source.
+- `INFERRED` means derived summary output that still requires review.
+- `AMBIGUOUS` means the source may be stale, incomplete, or unreliable.

agent_knowledge/assets/templates/project/agent-knowledge/Evidence/imports/README.md

@@ -0,0 +1,29 @@
+---
+note_type: evidence-imports
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - evidence
+  - imports
+---
+
+# Imported Evidence
+
+Use this branch for imported supporting material that is useful during backfill but should
+not be treated as canonical truth on its own.
+
+Expected files include:
+
+- `existing-docs.txt`
+- `doc-index.txt`
+- `tasks.txt`
+- `session-files.txt`
+- `cursor-sessions.txt`
+- `trace-index.txt`
+- `structural-summary.md`
+- `graphify/` (optional)
+
+Imported or generated evidence may include adjacent `.meta.json` files with source,
+kind, confidence, generated_at, related_paths, and notes.

agent_knowledge/assets/templates/project/agent-knowledge/Evidence/raw/README.md

@@ -0,0 +1,25 @@
+---
+note_type: evidence-raw
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - evidence
+  - raw
+---
+
+# Raw Evidence
+
+Use this branch for direct snapshots collected from the current codebase and repo state.
+
+Expected files include:
+
+- `git-log.txt`
+- `git-log-detail.txt`
+- `git-authors.txt`
+- `structure.txt`
+- `manifests.txt`
+- `config-files.txt`
+- `tests.txt`
+- `ci-workflows.txt`

agent_knowledge/assets/templates/project/agent-knowledge/Memory/MEMORY.md

@@ -0,0 +1,37 @@
+---
+note_type: durable-memory-root
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - memory
+---
+
+# Memory: <project-name>
+
+## Purpose
+
+Landing page for curated project memory. Keep this file short and use it to route into
+the right branch notes.
+
+## Current State
+
+- Project memory has been initialized but not yet populated.
+- The agent should inspect the repo and create initial branch notes.
+
+## Recent Changes
+
+- <date> - Created durable memory root.
+
+## Decisions
+
+- [decisions/decisions.md](decisions/decisions.md) - Decision log.
+
+## Open Questions
+
+- Which areas of the project should become the first memory branches?
+
+## Branches
+
+- Add branch links here as the agent infers project structure.

agent_knowledge/assets/templates/project/agent-knowledge/Memory/decisions/decisions.md

@@ -0,0 +1,31 @@
+---
+note_type: decision-log
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - decision
+---
+
+# Decisions
+
+## Purpose
+
+Architectural and process decisions that affect this project.
+
+## Current State
+
+- No decisions recorded yet.
+
+## Recent Changes
+
+- <date> - Created decision log.
+
+## Decisions
+
+- None recorded yet.
+
+## Open Questions
+
+- Which existing choices should be captured as explicit decisions?

agent_knowledge/assets/templates/project/agent-knowledge/Outputs/README.md

@@ -0,0 +1,24 @@
+---
+note_type: outputs-index
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - outputs
+---
+
+# Outputs
+
+Use this branch for generated outputs that are useful to keep near project memory.
+Outputs are orientation artifacts first, not durable canonical memory.
+
+Examples:
+
+- release handoff notes
+- generated summaries kept alongside project knowledge
+- ad hoc reports
+- `architecture-summary.md`
+- `structural-map.md`
+- `graphify/` summaries
+- `token-measurements/` reports and task-run logs

agent_knowledge/assets/templates/project/agent-knowledge/STATUS.md

@@ -0,0 +1,43 @@
+---
+note_type: knowledge-status
+project: <project-name>
+profile_hint: <profile-type>
+ontology_model: 2
+real_knowledge_path: <absolute-path-to-dedicated-knowledge-folder>
+local_pointer_path: ./agent-knowledge
+last_bootstrap:
+onboarding: pending
+last_backfill_import:
+last_project_sync:
+last_global_sync:
+last_graph_sync:
+last_compaction:
+last_validation:
+last_validation_result: unknown
+last_doctor:
+last_doctor_result: unknown
+---
+
+# Knowledge Status: <project-name>
+
+## Current State
+
+- Profile hint: `<profile-type>`
+- Real knowledge path: `<absolute-path-to-dedicated-knowledge-folder>`
+- Local pointer path: `./agent-knowledge`
+- Onboarding: `pending`
+
+## Activity
+
+- Last bootstrap: `not-yet`
+- Last backfill/import: `not-yet`
+- Last project sync: `not-yet`
+- Last global sync: `not-yet`
+- Last graph sync: `not-yet`
+- Last compaction: `not-yet`
+- Last validation: `not-yet` (`unknown`)
+- Last doctor: `not-yet` (`unknown`)
+
+## Health Warnings
+
+- None.

agent_knowledge/assets/templates/project/agent-knowledge/Sessions/README.md

@@ -0,0 +1,21 @@
+---
+note_type: session-index
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - sessions
+---
+
+# Sessions
+
+Session notes are ephemeral and milestone-oriented.
+
+Use this branch for:
+
+- current milestones
+- blockers
+- handoff notes between active sessions
+
+Do not treat this branch as durable memory.

agent_knowledge/assets/templates/project/agent-knowledge/Templates/README.md

@@ -0,0 +1,19 @@
+---
+note_type: template-index
+project: <project-name>
+status: active
+last_updated: <date>
+tags:
+  - agent-knowledge
+  - templates
+---
+
+# Templates
+
+Use this branch for project-local note templates when the framework templates are not enough.
+
+Start from the framework repo first:
+
+- `templates/memory/`
+- `templates/dashboards/`
+- `templates/project/`

agent_knowledge/assets/templates/project/gitignore.agent-knowledge

@@ -0,0 +1,13 @@
+# Recommended ignores for connected projects using a dedicated knowledge folder.
+# Keep or remove the local pointer based on your repo policy.
+
+# If agent-knowledge is a symlink, many teams keep the pointer tracked.
+# If you prefer it untracked, uncomment the next line.
+# agent-knowledge/
+
+# Usually ignore noisy generated or transient knowledge branches.
+agent-knowledge/Evidence/
+agent-knowledge/Sessions/
+agent-knowledge/Outputs/
+agent-knowledge/.obsidian/workspace*.json
+agent-knowledge/.obsidian/cache/