agent-knowledge-cli 0.1.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_knowledge/__init__.py +3 -0
- agent_knowledge/__main__.py +3 -0
- agent_knowledge/assets/__init__.py +0 -0
- agent_knowledge/assets/claude/global.md +44 -0
- agent_knowledge/assets/claude/project-template.md +46 -0
- agent_knowledge/assets/claude/scripts/install.sh +85 -0
- agent_knowledge/assets/commands/doctor.md +21 -0
- agent_knowledge/assets/commands/global-knowledge-sync.md +27 -0
- agent_knowledge/assets/commands/graphify-sync.md +26 -0
- agent_knowledge/assets/commands/knowledge-sync.md +26 -0
- agent_knowledge/assets/commands/ship.md +29 -0
- agent_knowledge/assets/rules/generate-architecture-doc.mdc +87 -0
- agent_knowledge/assets/rules/history-backfill.mdc +67 -0
- agent_knowledge/assets/rules/memory-bootstrap.mdc +53 -0
- agent_knowledge/assets/rules/memory-writeback.mdc +90 -0
- agent_knowledge/assets/rules/shared-memory.mdc +102 -0
- agent_knowledge/assets/rules/workflow-orchestration.mdc +93 -0
- agent_knowledge/assets/rules-global/action-first.mdc +26 -0
- agent_knowledge/assets/rules-global/no-icons-emojis.mdc +16 -0
- agent_knowledge/assets/rules-global/no-unsolicited-docs.mdc +20 -0
- agent_knowledge/assets/scripts/bootstrap-memory-tree.sh +389 -0
- agent_knowledge/assets/scripts/compact-memory.sh +191 -0
- agent_knowledge/assets/scripts/doctor.sh +137 -0
- agent_knowledge/assets/scripts/global-knowledge-sync.sh +372 -0
- agent_knowledge/assets/scripts/graphify-sync.sh +397 -0
- agent_knowledge/assets/scripts/import-agent-history.sh +706 -0
- agent_knowledge/assets/scripts/install-project-links.sh +258 -0
- agent_knowledge/assets/scripts/lib/knowledge-common.sh +875 -0
- agent_knowledge/assets/scripts/measure-token-savings.py +540 -0
- agent_knowledge/assets/scripts/ship.sh +256 -0
- agent_knowledge/assets/scripts/update-knowledge.sh +341 -0
- agent_knowledge/assets/scripts/validate-knowledge.sh +265 -0
- agent_knowledge/assets/skills/decision-recording/SKILL.md +124 -0
- agent_knowledge/assets/skills/history-backfill/SKILL.md +115 -0
- agent_knowledge/assets/skills/memory-compaction/SKILL.md +115 -0
- agent_knowledge/assets/skills/memory-management/SKILL.md +134 -0
- agent_knowledge/assets/skills/project-ontology-bootstrap/SKILL.md +173 -0
- agent_knowledge/assets/skills/session-management/SKILL.md +116 -0
- agent_knowledge/assets/skills-cursor/create-rule/SKILL.md +164 -0
- agent_knowledge/assets/skills-cursor/create-skill/SKILL.md +498 -0
- agent_knowledge/assets/skills-cursor/create-subagent/SKILL.md +225 -0
- agent_knowledge/assets/skills-cursor/migrate-to-skills/SKILL.md +134 -0
- agent_knowledge/assets/skills-cursor/shell/SKILL.md +24 -0
- agent_knowledge/assets/skills-cursor/update-cursor-settings/SKILL.md +122 -0
- agent_knowledge/assets/templates/dashboards/project-overview.template.md +24 -0
- agent_knowledge/assets/templates/dashboards/session-rollup.template.md +23 -0
- agent_knowledge/assets/templates/hooks/hooks.json.template +11 -0
- agent_knowledge/assets/templates/integrations/claude/CLAUDE.md +7 -0
- agent_knowledge/assets/templates/integrations/codex/AGENTS.md +7 -0
- agent_knowledge/assets/templates/integrations/cursor/agent-knowledge.mdc +11 -0
- agent_knowledge/assets/templates/integrations/cursor/hooks.json +11 -0
- agent_knowledge/assets/templates/memory/MEMORY.root.template.md +36 -0
- agent_knowledge/assets/templates/memory/branch.template.md +33 -0
- agent_knowledge/assets/templates/memory/decision.template.md +33 -0
- agent_knowledge/assets/templates/memory/profile.hybrid.yaml +16 -0
- agent_knowledge/assets/templates/memory/profile.ml-platform.yaml +18 -0
- agent_knowledge/assets/templates/memory/profile.robotics.yaml +19 -0
- agent_knowledge/assets/templates/memory/profile.web-app.yaml +16 -0
- agent_knowledge/assets/templates/portfolio/.obsidian/README.md +21 -0
- agent_knowledge/assets/templates/portfolio/.obsidian/app.json +5 -0
- agent_knowledge/assets/templates/portfolio/.obsidian/core-plugins.json +7 -0
- agent_knowledge/assets/templates/project/.agent-project.yaml +36 -0
- agent_knowledge/assets/templates/project/.agentknowledgeignore +10 -0
- agent_knowledge/assets/templates/project/AGENTS.md +87 -0
- agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/README.md +23 -0
- agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/app.json +5 -0
- agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/core-plugins.json +7 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Evidence/README.md +34 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Evidence/imports/README.md +29 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Evidence/raw/README.md +25 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Memory/MEMORY.md +37 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Memory/decisions/decisions.md +31 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Outputs/README.md +24 -0
- agent_knowledge/assets/templates/project/agent-knowledge/STATUS.md +43 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Sessions/README.md +21 -0
- agent_knowledge/assets/templates/project/agent-knowledge/Templates/README.md +19 -0
- agent_knowledge/assets/templates/project/gitignore.agent-knowledge +13 -0
- agent_knowledge/cli.py +457 -0
- agent_knowledge/runtime/__init__.py +0 -0
- agent_knowledge/runtime/integrations.py +154 -0
- agent_knowledge/runtime/paths.py +46 -0
- agent_knowledge/runtime/shell.py +22 -0
- agent_knowledge/runtime/sync.py +255 -0
- agent_knowledge_cli-0.1.2.dist-info/METADATA +155 -0
- agent_knowledge_cli-0.1.2.dist-info/RECORD +88 -0
- agent_knowledge_cli-0.1.2.dist-info/WHEEL +4 -0
- agent_knowledge_cli-0.1.2.dist-info/entry_points.txt +2 -0
- agent_knowledge_cli-0.1.2.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
"""Sync logic: memory branch sync, session rollup, git-log evidence extraction."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime
|
|
6
|
+
import re
|
|
7
|
+
import shutil
|
|
8
|
+
import subprocess
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _now_iso() -> str:
|
|
13
|
+
return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _today() -> str:
|
|
17
|
+
return datetime.date.today().isoformat()
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
# ---------------------------------------------------------------------------
|
|
21
|
+
# 1. Memory branch sync: agent_docs/memory/ -> agent-knowledge/Memory/
|
|
22
|
+
# ---------------------------------------------------------------------------
|
|
23
|
+
|
|
24
|
+
def sync_memory_branches(
|
|
25
|
+
repo: Path,
|
|
26
|
+
*,
|
|
27
|
+
dry_run: bool = False,
|
|
28
|
+
) -> list[str]:
|
|
29
|
+
"""Copy agent_docs/memory/*.md into the vault's Memory/ branch.
|
|
30
|
+
|
|
31
|
+
Only copies files that are newer or missing in the vault.
|
|
32
|
+
Returns a list of action strings for reporting.
|
|
33
|
+
"""
|
|
34
|
+
src_dir = repo / "agent_docs" / "memory"
|
|
35
|
+
dst_dir = repo / "agent-knowledge" / "Memory"
|
|
36
|
+
actions: list[str] = []
|
|
37
|
+
|
|
38
|
+
if not src_dir.is_dir():
|
|
39
|
+
actions.append("skip: agent_docs/memory/ not found")
|
|
40
|
+
return actions
|
|
41
|
+
|
|
42
|
+
if not dst_dir.is_dir():
|
|
43
|
+
actions.append("skip: agent-knowledge/Memory/ not found")
|
|
44
|
+
return actions
|
|
45
|
+
|
|
46
|
+
for src_file in sorted(src_dir.rglob("*.md")):
|
|
47
|
+
rel = src_file.relative_to(src_dir)
|
|
48
|
+
dst_file = dst_dir / rel
|
|
49
|
+
|
|
50
|
+
if dst_file.exists():
|
|
51
|
+
src_mtime = src_file.stat().st_mtime
|
|
52
|
+
dst_mtime = dst_file.stat().st_mtime
|
|
53
|
+
if src_mtime <= dst_mtime:
|
|
54
|
+
continue
|
|
55
|
+
|
|
56
|
+
already_exists = dst_file.exists()
|
|
57
|
+
if dry_run:
|
|
58
|
+
verb = "would update" if already_exists else "would create"
|
|
59
|
+
actions.append(f" [dry-run] {verb}: Memory/{rel}")
|
|
60
|
+
else:
|
|
61
|
+
dst_file.parent.mkdir(parents=True, exist_ok=True)
|
|
62
|
+
shutil.copy2(src_file, dst_file)
|
|
63
|
+
verb = "updated" if already_exists else "created"
|
|
64
|
+
actions.append(f" {verb}: Memory/{rel}")
|
|
65
|
+
|
|
66
|
+
if not actions:
|
|
67
|
+
actions.append(" up to date")
|
|
68
|
+
|
|
69
|
+
return actions
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
# ---------------------------------------------------------------------------
|
|
73
|
+
# 2. Session rollup: Sessions/*.md -> Dashboards/session-rollup.md
|
|
74
|
+
# ---------------------------------------------------------------------------
|
|
75
|
+
|
|
76
|
+
_FRONTMATTER_RE = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def rollup_sessions(
|
|
80
|
+
repo: Path,
|
|
81
|
+
*,
|
|
82
|
+
dry_run: bool = False,
|
|
83
|
+
max_sessions: int = 10,
|
|
84
|
+
) -> list[str]:
|
|
85
|
+
"""Scan Sessions/ for .md files, append summaries to session-rollup.md."""
|
|
86
|
+
sessions_dir = repo / "agent-knowledge" / "Sessions"
|
|
87
|
+
rollup_path = repo / "agent-knowledge" / "Dashboards" / "session-rollup.md"
|
|
88
|
+
actions: list[str] = []
|
|
89
|
+
|
|
90
|
+
if not sessions_dir.is_dir():
|
|
91
|
+
actions.append("skip: Sessions/ not found")
|
|
92
|
+
return actions
|
|
93
|
+
|
|
94
|
+
session_files = sorted(
|
|
95
|
+
[f for f in sessions_dir.glob("*.md") if f.name != "README.md"],
|
|
96
|
+
key=lambda f: f.stat().st_mtime,
|
|
97
|
+
reverse=True,
|
|
98
|
+
)[:max_sessions]
|
|
99
|
+
|
|
100
|
+
if not session_files:
|
|
101
|
+
actions.append(" no session files to roll up")
|
|
102
|
+
return actions
|
|
103
|
+
|
|
104
|
+
entries: list[str] = []
|
|
105
|
+
for sf in session_files:
|
|
106
|
+
body = sf.read_text(errors="replace")
|
|
107
|
+
body = _FRONTMATTER_RE.sub("", body).strip()
|
|
108
|
+
title_match = re.match(r"^#\s+(.+)", body)
|
|
109
|
+
title = title_match.group(1) if title_match else sf.stem
|
|
110
|
+
first_lines = "\n".join(body.split("\n")[:5])
|
|
111
|
+
entries.append(f"### {title}\n\n_Source: {sf.name}_\n\n{first_lines}\n")
|
|
112
|
+
|
|
113
|
+
rollup_body = f"""\
|
|
114
|
+
---
|
|
115
|
+
note_type: dashboard
|
|
116
|
+
dashboard: session-rollup
|
|
117
|
+
project: {repo.name}
|
|
118
|
+
last_updated: {_today()}
|
|
119
|
+
tags:
|
|
120
|
+
- {repo.name}
|
|
121
|
+
- dashboard
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
# Session Rollup
|
|
125
|
+
|
|
126
|
+
## Recent Sessions ({len(entries)} files)
|
|
127
|
+
|
|
128
|
+
{"---".join(entries)}
|
|
129
|
+
|
|
130
|
+
## Next Review
|
|
131
|
+
|
|
132
|
+
- Review recent sessions before the next compaction or handoff.
|
|
133
|
+
"""
|
|
134
|
+
|
|
135
|
+
if dry_run:
|
|
136
|
+
actions.append(f" [dry-run] would update: Dashboards/session-rollup.md ({len(entries)} sessions)")
|
|
137
|
+
else:
|
|
138
|
+
rollup_path.parent.mkdir(parents=True, exist_ok=True)
|
|
139
|
+
rollup_path.write_text(rollup_body)
|
|
140
|
+
actions.append(f" updated: Dashboards/session-rollup.md ({len(entries)} sessions)")
|
|
141
|
+
|
|
142
|
+
return actions
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
# ---------------------------------------------------------------------------
|
|
146
|
+
# 3. Git log extraction -> Evidence/raw/git-recent.md
|
|
147
|
+
# ---------------------------------------------------------------------------
|
|
148
|
+
|
|
149
|
+
def extract_git_log(
|
|
150
|
+
repo: Path,
|
|
151
|
+
*,
|
|
152
|
+
dry_run: bool = False,
|
|
153
|
+
count: int = 30,
|
|
154
|
+
) -> list[str]:
|
|
155
|
+
"""Run git log and write recent commits to Evidence/raw/git-recent.md."""
|
|
156
|
+
evidence_dir = repo / "agent-knowledge" / "Evidence" / "raw"
|
|
157
|
+
actions: list[str] = []
|
|
158
|
+
|
|
159
|
+
try:
|
|
160
|
+
result = subprocess.run(
|
|
161
|
+
["git", "log", f"--oneline", f"-{count}", "--no-decorate"],
|
|
162
|
+
capture_output=True,
|
|
163
|
+
text=True,
|
|
164
|
+
cwd=str(repo),
|
|
165
|
+
timeout=10,
|
|
166
|
+
)
|
|
167
|
+
if result.returncode != 0:
|
|
168
|
+
actions.append(f" skip: git log failed ({result.stderr.strip()[:80]})")
|
|
169
|
+
return actions
|
|
170
|
+
except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
|
|
171
|
+
actions.append(f" skip: git not available ({exc})")
|
|
172
|
+
return actions
|
|
173
|
+
|
|
174
|
+
lines = result.stdout.strip()
|
|
175
|
+
if not lines:
|
|
176
|
+
actions.append(" skip: no git history")
|
|
177
|
+
return actions
|
|
178
|
+
|
|
179
|
+
content = f"""\
|
|
180
|
+
---
|
|
181
|
+
note_type: evidence
|
|
182
|
+
source: git-log
|
|
183
|
+
extracted: {_now_iso()}
|
|
184
|
+
commits: {len(lines.splitlines())}
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
# Recent Git History
|
|
188
|
+
|
|
189
|
+
Last {count} commits as of {_today()}.
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
{lines}
|
|
193
|
+
```
|
|
194
|
+
"""
|
|
195
|
+
|
|
196
|
+
dst = evidence_dir / "git-recent.md"
|
|
197
|
+
if dry_run:
|
|
198
|
+
actions.append(f" [dry-run] would write: Evidence/raw/git-recent.md ({len(lines.splitlines())} commits)")
|
|
199
|
+
else:
|
|
200
|
+
evidence_dir.mkdir(parents=True, exist_ok=True)
|
|
201
|
+
dst.write_text(content)
|
|
202
|
+
actions.append(f" wrote: Evidence/raw/git-recent.md ({len(lines.splitlines())} commits)")
|
|
203
|
+
|
|
204
|
+
return actions
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
# ---------------------------------------------------------------------------
|
|
208
|
+
# 4. Update STATUS.md timestamps
|
|
209
|
+
# ---------------------------------------------------------------------------
|
|
210
|
+
|
|
211
|
+
def stamp_status(repo: Path, field: str) -> None:
|
|
212
|
+
"""Update a timestamp field in STATUS.md frontmatter."""
|
|
213
|
+
status_path = repo / "agent-knowledge" / "STATUS.md"
|
|
214
|
+
if not status_path.is_file():
|
|
215
|
+
return
|
|
216
|
+
|
|
217
|
+
text = status_path.read_text()
|
|
218
|
+
now = _now_iso()
|
|
219
|
+
today = _today()
|
|
220
|
+
|
|
221
|
+
pattern = re.compile(rf"^({re.escape(field)}:[ \t]*).*$", re.MULTILINE)
|
|
222
|
+
if pattern.search(text):
|
|
223
|
+
text = pattern.sub(rf"\g<1>{now}", text)
|
|
224
|
+
|
|
225
|
+
display_field = field.replace("_", " ").replace("last ", "Last ")
|
|
226
|
+
display_pattern = re.compile(
|
|
227
|
+
rf"^(- {re.escape(display_field)}:[ \t]*`).*(`[ \t]*)$",
|
|
228
|
+
re.MULTILINE | re.IGNORECASE,
|
|
229
|
+
)
|
|
230
|
+
if display_pattern.search(text):
|
|
231
|
+
text = display_pattern.sub(rf"\g<1>{now}\2", text)
|
|
232
|
+
|
|
233
|
+
status_path.write_text(text)
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
# ---------------------------------------------------------------------------
|
|
237
|
+
# 5. Top-level sync orchestrator
|
|
238
|
+
# ---------------------------------------------------------------------------
|
|
239
|
+
|
|
240
|
+
def run_sync(
|
|
241
|
+
repo: Path,
|
|
242
|
+
*,
|
|
243
|
+
dry_run: bool = False,
|
|
244
|
+
) -> dict[str, list[str]]:
|
|
245
|
+
"""Run all sync steps. Returns a dict of step -> action list."""
|
|
246
|
+
results: dict[str, list[str]] = {}
|
|
247
|
+
|
|
248
|
+
results["memory-branches"] = sync_memory_branches(repo, dry_run=dry_run)
|
|
249
|
+
results["session-rollup"] = rollup_sessions(repo, dry_run=dry_run)
|
|
250
|
+
results["git-evidence"] = extract_git_log(repo, dry_run=dry_run)
|
|
251
|
+
|
|
252
|
+
if not dry_run:
|
|
253
|
+
stamp_status(repo, "last_project_sync")
|
|
254
|
+
|
|
255
|
+
return results
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-knowledge-cli
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Adaptive, file-based project knowledge for AI coding agents
|
|
5
|
+
Author: agent-knowledge contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Operating System :: MacOS
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Requires-Dist: click>=8.0
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: build; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
21
|
+
Provides-Extra: tokens
|
|
22
|
+
Requires-Dist: tiktoken; extra == 'tokens'
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# agent-knowledge
|
|
26
|
+
|
|
27
|
+
Persistent, file-based project memory for AI coding agents.
|
|
28
|
+
|
|
29
|
+
One command gives any project a knowledge vault that agents read on startup,
|
|
30
|
+
maintain during work, and carry across sessions -- no database, no server,
|
|
31
|
+
just markdown files and a CLI.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
pip install agent-knowledge-cli
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
cd your-project
|
|
43
|
+
agent-knowledge init
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Open Cursor, Claude, or Codex in the repo -- the agent picks up from there.
|
|
47
|
+
|
|
48
|
+
`init` automatically:
|
|
49
|
+
- infers the project slug from the directory name
|
|
50
|
+
- creates an external knowledge vault at `~/agent-os/projects/<slug>/`
|
|
51
|
+
- symlinks `./agent-knowledge` into the repo as the local handle
|
|
52
|
+
- detects Cursor, Claude, and Codex and installs integration files
|
|
53
|
+
- bootstraps the memory tree and marks onboarding as `pending`
|
|
54
|
+
- prints the prompt to kick off first-time agent ingestion
|
|
55
|
+
|
|
56
|
+
## How It Works
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
your-project/
|
|
60
|
+
.agent-project.yaml # project config
|
|
61
|
+
AGENTS.md # instructions agents read on startup
|
|
62
|
+
agent-knowledge/ # symlink -> ~/agent-os/projects/<slug>/
|
|
63
|
+
STATUS.md # onboarding state + sync timestamps
|
|
64
|
+
Memory/
|
|
65
|
+
MEMORY.md # root entrypoint (read first)
|
|
66
|
+
stack.md # flat branch note
|
|
67
|
+
perception/
|
|
68
|
+
perception.md # branch entry (same name as folder)
|
|
69
|
+
fusion.md # subtopic note
|
|
70
|
+
decisions/
|
|
71
|
+
decisions.md # decision log
|
|
72
|
+
Evidence/ # imported/extracted material
|
|
73
|
+
Outputs/ # generated views (never canonical)
|
|
74
|
+
Sessions/ # ephemeral session state
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Knowledge lives **outside** the repo so it persists across branches, tools,
|
|
78
|
+
and clones. The symlink gives every tool a stable `./agent-knowledge` path.
|
|
79
|
+
|
|
80
|
+
When an agent opens the repo it reads `AGENTS.md` and `STATUS.md`.
|
|
81
|
+
If onboarding is pending, it inspects the project, imports evidence,
|
|
82
|
+
infers the ontology from the actual repo, and writes curated memory.
|
|
83
|
+
After that, maintenance is automatic.
|
|
84
|
+
|
|
85
|
+
## Branch Convention
|
|
86
|
+
|
|
87
|
+
The memory tree uses a same-name branch-note convention:
|
|
88
|
+
|
|
89
|
+
- **Flat note** (`stack.md`): for topics with no subtopics
|
|
90
|
+
- **Folder** (`perception/perception.md`): for topics that grow subtopics
|
|
91
|
+
- **Folder name = topic**, entry note = same name as folder
|
|
92
|
+
- **Agents infer** the branch structure from the real project -- no fixed profiles
|
|
93
|
+
|
|
94
|
+
The agent starts small (2-4 branches) and grows the tree only when justified.
|
|
95
|
+
Hooks stay thin -- they detect changes and trigger updates, not rebuild the ontology.
|
|
96
|
+
|
|
97
|
+
## Commands
|
|
98
|
+
|
|
99
|
+
| Command | What it does |
|
|
100
|
+
|---------|-------------|
|
|
101
|
+
| `init` | Set up a project (zero-arg, auto-detects everything) |
|
|
102
|
+
| `sync` | Push memory updates + extract git evidence |
|
|
103
|
+
| `doctor` | Validate setup and report health |
|
|
104
|
+
| `update` | Sync project changes into the knowledge tree |
|
|
105
|
+
| `import` | Import repo history into Evidence/ |
|
|
106
|
+
| `ship` | Validate, sync, commit, push |
|
|
107
|
+
| `setup` | Install global Cursor rules and skills |
|
|
108
|
+
| `global-sync` | Import safe local tooling config |
|
|
109
|
+
| `measure-tokens` | Estimate context token savings |
|
|
110
|
+
|
|
111
|
+
All write commands support `--dry-run`. Use `--json` for machine-readable output.
|
|
112
|
+
|
|
113
|
+
## Multi-Tool Support
|
|
114
|
+
|
|
115
|
+
`init` detects which tools are present and installs the right bridge files:
|
|
116
|
+
|
|
117
|
+
| Tool | Bridge file | When installed |
|
|
118
|
+
|------|-------------|---------------|
|
|
119
|
+
| Cursor | `.cursor/hooks.json` + `.cursor/rules/agent-knowledge.mdc` | Always (hooks/rules are inert outside Cursor) |
|
|
120
|
+
| Claude | `CLAUDE.md` | When `.claude/` directory is detected |
|
|
121
|
+
| Codex | `.codex/AGENTS.md` | When `.codex/` directory is detected |
|
|
122
|
+
|
|
123
|
+
Multiple tools in the same repo work together.
|
|
124
|
+
|
|
125
|
+
## Obsidian
|
|
126
|
+
|
|
127
|
+
Open `~/agent-os/projects/<slug>/` as an Obsidian vault. The knowledge graph
|
|
128
|
+
shows all memory areas, evidence, and dashboards connected through wiki-links.
|
|
129
|
+
|
|
130
|
+
Enable **Graph view** in Settings > Core plugins and set
|
|
131
|
+
**Files and links > Use `[[Wikilinks]]`** to ON for the best experience.
|
|
132
|
+
|
|
133
|
+
## Custom Knowledge Home
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
export AGENT_KNOWLEDGE_HOME=~/my-knowledge
|
|
137
|
+
agent-knowledge init
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Platform Support
|
|
141
|
+
|
|
142
|
+
- **macOS** and **Linux** are fully supported.
|
|
143
|
+
- **Windows** is not currently supported. The CLI relies on `bash` and POSIX shell
|
|
144
|
+
scripts for most operations.
|
|
145
|
+
- Python 3.9+ is required.
|
|
146
|
+
|
|
147
|
+
## Development
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
git clone <repo-url>
|
|
151
|
+
cd agent-knowledge
|
|
152
|
+
python -m venv .venv && source .venv/bin/activate
|
|
153
|
+
pip install -e ".[dev]"
|
|
154
|
+
python -m pytest tests/ -q
|
|
155
|
+
```
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
agent_knowledge/__init__.py,sha256=4yXbumzvmbIMyx0crYzd-GklW5GfsfvxbIC1NZ7r-6A,107
|
|
2
|
+
agent_knowledge/__main__.py,sha256=sRgghhEmc_3c0X0wPaPnaHumQfOlG359HHl3H94SmE4,45
|
|
3
|
+
agent_knowledge/cli.py,sha256=kBVY_9qv1sRpSHZMo227ne1-m5ns3_zaib3x9k6o14w,17337
|
|
4
|
+
agent_knowledge/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
agent_knowledge/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
agent_knowledge/runtime/integrations.py,sha256=nVzOGtgNLFeiHOeB84hVCES4BPM0xE4xt0EHCR0hq08,5023
|
|
7
|
+
agent_knowledge/runtime/paths.py,sha256=7C3JSW7P9UxlzK7b0t83eT5n3cLBGDe6uMDgE5AYlL0,1609
|
|
8
|
+
agent_knowledge/runtime/shell.py,sha256=G48NgJ3cJw48sctW83C8Fx6dzw2kFCXksQPzUF-zPBA,638
|
|
9
|
+
agent_knowledge/runtime/sync.py,sha256=5G97lF82EK4BKkQWKwFLA2pOrhkEfzvYkDV6LB41dig,7668
|
|
10
|
+
agent_knowledge/assets/claude/global.md,sha256=DCI3Rv56e_tq3si31cSBXnFvEu4B4Pl5zHEorx__0ok,2045
|
|
11
|
+
agent_knowledge/assets/claude/project-template.md,sha256=DiwtEGqCN-fSowU-tH5BlqJKK4U1216Yc4nFuVlxTu0,1411
|
|
12
|
+
agent_knowledge/assets/claude/scripts/install.sh,sha256=o101Ktvw9kiYvZ4H1mcETliviKfcX_ybraETc5U8s7Y,2370
|
|
13
|
+
agent_knowledge/assets/commands/doctor.md,sha256=mlJonQssFucpek8AU9WyZf4InyVTEhD3bb7naGkh4TI,577
|
|
14
|
+
agent_knowledge/assets/commands/global-knowledge-sync.md,sha256=pYy-tWvV9gLeWvDnuFjPRC8_UMMU7BLfV192-UUdQyY,1002
|
|
15
|
+
agent_knowledge/assets/commands/graphify-sync.md,sha256=gyoarPW4aO1MyuQdhGoPxTE_W6HSxEGe5EJ2OIDb0nk,1138
|
|
16
|
+
agent_knowledge/assets/commands/knowledge-sync.md,sha256=xmCHLFIA1XWd_zQXmEUCCMsStAjiyhK_5bTjg0Ak5TE,1008
|
|
17
|
+
agent_knowledge/assets/commands/ship.md,sha256=LixKH2p_5ZfaY153qh4jDDtidEJDAUHGgONtTW9c5Os,1020
|
|
18
|
+
agent_knowledge/assets/rules/generate-architecture-doc.mdc,sha256=A8NzVouPLo21EwPTY2jO7CXz_x80NULp8mrcfTxxIbU,4069
|
|
19
|
+
agent_knowledge/assets/rules/history-backfill.mdc,sha256=Rl594tnPA-GRuvekEN36M61vZAUBtZF3NMpqUhXfOaw,2841
|
|
20
|
+
agent_knowledge/assets/rules/memory-bootstrap.mdc,sha256=FVcT3GYTy6ZCT9RzJ9jzHEuXSxeFgq57mHm4u4ubG5M,2387
|
|
21
|
+
agent_knowledge/assets/rules/memory-writeback.mdc,sha256=2Hz7ANMP549GtOM5HJC-YaoVbxm692yddUOsqMOWvo0,3320
|
|
22
|
+
agent_knowledge/assets/rules/shared-memory.mdc,sha256=aFjkHA0otZR36-1m6k8Y0TzsKZTct7M_Hf-9g9sGF5A,3975
|
|
23
|
+
agent_knowledge/assets/rules/workflow-orchestration.mdc,sha256=rgA5_iXWk4PtK5CQcW1m1-nR7pUeyQMGiZarsrot5L8,3398
|
|
24
|
+
agent_knowledge/assets/rules-global/action-first.mdc,sha256=IvRQNmlcaPQG9HIKu-mjCnnrT9RxQNV-PUNhIQOE5VU,713
|
|
25
|
+
agent_knowledge/assets/rules-global/no-icons-emojis.mdc,sha256=IC8HXSz3rJxnYPc2PAAXKKWp1ceiwx8ngnDQUTxjdDw,275
|
|
26
|
+
agent_knowledge/assets/rules-global/no-unsolicited-docs.mdc,sha256=cBtKyVkq-JcgD7DhJ25_UWxOzYSPuSAfMHcnXmztbwA,538
|
|
27
|
+
agent_knowledge/assets/scripts/bootstrap-memory-tree.sh,sha256=BoxU_dDeMrmIkyg-0eo_L39VHI5fmGhYkoMECSabD3c,14601
|
|
28
|
+
agent_knowledge/assets/scripts/compact-memory.sh,sha256=u3PWcNV0eKXNv-XClfmaTpSCXuBqlJUQYyUyoqt5fVA,4495
|
|
29
|
+
agent_knowledge/assets/scripts/doctor.sh,sha256=mMBkgfzPJz29HuG9ylULRApx8dNpEHKS2_D_vg8Nugs,4041
|
|
30
|
+
agent_knowledge/assets/scripts/global-knowledge-sync.sh,sha256=sllqlvcBX2wjwCKvPAh-5gXYGLq8ihCEYkdZ9hWL-pQ,13185
|
|
31
|
+
agent_knowledge/assets/scripts/graphify-sync.sh,sha256=8ftPxYKq0Kya62udVZYMOkpUylhuxGaXXhJr2IhYow0,12387
|
|
32
|
+
agent_knowledge/assets/scripts/import-agent-history.sh,sha256=lMgysoT4lintmY-hBjkSiNVAVQ0N33ut51EV6TqU-Rw,28549
|
|
33
|
+
agent_knowledge/assets/scripts/install-project-links.sh,sha256=vp-uVpZHRunCcuJF7rliHs_Yo2GGuVB1nVTWAJx7aSA,8121
|
|
34
|
+
agent_knowledge/assets/scripts/measure-token-savings.py,sha256=j2RsxiokrwXHnatMfMxyjrIwE3q7hYbVto8GEOno_60,18781
|
|
35
|
+
agent_knowledge/assets/scripts/ship.sh,sha256=cM6qz_DS9ubMOiUUrdqU1BOJNUWhTL3iTco_ELLl0Rs,8029
|
|
36
|
+
agent_knowledge/assets/scripts/update-knowledge.sh,sha256=5NKsZE7MdwgrBr4LMoKJZRoTxkaRQgnSJsk0TnfUMu8,11180
|
|
37
|
+
agent_knowledge/assets/scripts/validate-knowledge.sh,sha256=7D6ZMffqE6FZY_UgcGe_9VHzkxCVNrJ2_Whhy9mCYwM,8309
|
|
38
|
+
agent_knowledge/assets/scripts/lib/knowledge-common.sh,sha256=lgsl-3T1e6OVvJZrm6V9_tNQmGWikXIQ7LbiibxKY3w,24464
|
|
39
|
+
agent_knowledge/assets/skills/decision-recording/SKILL.md,sha256=VrGkAPLpoxjaGLljDcoI9Q2h6TWwWFCKNnCwmW7Se0U,3433
|
|
40
|
+
agent_knowledge/assets/skills/history-backfill/SKILL.md,sha256=s2zKtTKejsw4GKKO9KNsE7xdA51qGcVdujkQZXNoyXY,4797
|
|
41
|
+
agent_knowledge/assets/skills/memory-compaction/SKILL.md,sha256=fHH7sN4JOjvBlhUnZoRYKyj1xA6sq6WHXIMKTbZ8tSI,3544
|
|
42
|
+
agent_knowledge/assets/skills/memory-management/SKILL.md,sha256=O5xiwYdeTxEw_Bu6N-4wZyPPBX9P0GNMeHLUNRRyCas,4931
|
|
43
|
+
agent_knowledge/assets/skills/project-ontology-bootstrap/SKILL.md,sha256=tNtLPsytki6zpzyac_GdisUJwt61vRWcdq7ueERzts0,5433
|
|
44
|
+
agent_knowledge/assets/skills/session-management/SKILL.md,sha256=nTPTB1LSBN9o2LA6q70T-UgE1TwLh5KXMHMDBxSInhU,3689
|
|
45
|
+
agent_knowledge/assets/skills-cursor/create-rule/SKILL.md,sha256=_oSZ3-k-2_gwbfcEmKfqNXLgyLNAYHE3y8g2BRUgJjw,3636
|
|
46
|
+
agent_knowledge/assets/skills-cursor/create-skill/SKILL.md,sha256=-YBkSXwV1Vf_ryyBKZ98UUtCxCwgnE8e_fsO-MXepas,14046
|
|
47
|
+
agent_knowledge/assets/skills-cursor/create-subagent/SKILL.md,sha256=q0aoD5DLOBDDGCpVuXWxO89y4A5_qQfPSfs6MKAqOSI,6454
|
|
48
|
+
agent_knowledge/assets/skills-cursor/migrate-to-skills/SKILL.md,sha256=eMBIPMluo9yDPzRO2SjUJa_wxkz8sCdZ_l7-SpE6W2s,6439
|
|
49
|
+
agent_knowledge/assets/skills-cursor/shell/SKILL.md,sha256=s1TOKMcK8dXAW7a_BwoYI_rdRwUwmTqycaHPy-V61P4,867
|
|
50
|
+
agent_knowledge/assets/skills-cursor/update-cursor-settings/SKILL.md,sha256=i17hp03JZPXCQKGOC3QCBR4NH2iOfbMDcEggchOg540,4296
|
|
51
|
+
agent_knowledge/assets/templates/dashboards/project-overview.template.md,sha256=9mo4ZQaPYzQd_Blx2Dmqo5dyi8qYnnBkrCQ6IjZLOXw,494
|
|
52
|
+
agent_knowledge/assets/templates/dashboards/session-rollup.template.md,sha256=BL0DsrPfei0IZWmZgA0gL4HLBhwlfxy6Y3RjSECml5c,390
|
|
53
|
+
agent_knowledge/assets/templates/hooks/hooks.json.template,sha256=6qfsifxUNIuYC7QCDD0wyb6hn7MAryLATYe7riV77fI,304
|
|
54
|
+
agent_knowledge/assets/templates/integrations/claude/CLAUDE.md,sha256=dbSDB-rNLWv4Fl84u0NWB26cFJ0s9W3X0NZfKPn5n9o,281
|
|
55
|
+
agent_knowledge/assets/templates/integrations/codex/AGENTS.md,sha256=KvpnywSPKvUu6C_CDPcv-IMFo5gXWsos8zj1koycFxU,299
|
|
56
|
+
agent_knowledge/assets/templates/integrations/cursor/agent-knowledge.mdc,sha256=nN_t04Xc1RTKxXBR4OFjJ-uDDJ_ECB00e5sgtJuTl_4,390
|
|
57
|
+
agent_knowledge/assets/templates/integrations/cursor/hooks.json,sha256=6qfsifxUNIuYC7QCDD0wyb6hn7MAryLATYe7riV77fI,304
|
|
58
|
+
agent_knowledge/assets/templates/memory/MEMORY.root.template.md,sha256=tAqMQ1g2Vis5eQ85eQKPJypP9Io_UHfLuW9ZdJiv1T4,472
|
|
59
|
+
agent_knowledge/assets/templates/memory/branch.template.md,sha256=Qfrk9anDWVqLOq63sqwF2fYG_Vch4KrL6Ybbzp9TOcc,365
|
|
60
|
+
agent_knowledge/assets/templates/memory/decision.template.md,sha256=3wKUrWohfOiXuhSrXkHCx2J-moM3YxilVssrYfrbFek,367
|
|
61
|
+
agent_knowledge/assets/templates/memory/profile.hybrid.yaml,sha256=Jq37b_pRlIYkSqVcO2_dZ9hX3FMcQ3qN0qIOhKGjIaQ,616
|
|
62
|
+
agent_knowledge/assets/templates/memory/profile.ml-platform.yaml,sha256=fSBCI5qDDFO5Ird35SYVuH6gXMgMZvTycvyHJwqgrrI,716
|
|
63
|
+
agent_knowledge/assets/templates/memory/profile.robotics.yaml,sha256=pHJYYNEN7-5bg8zJSntDbv4AvIX7PUIz_s3ePwebyKg,654
|
|
64
|
+
agent_knowledge/assets/templates/memory/profile.web-app.yaml,sha256=li9S0ErtgumhztTZzE3aRp-CRTPvJSN3xwPuh4jT7aM,544
|
|
65
|
+
agent_knowledge/assets/templates/portfolio/.obsidian/README.md,sha256=Pq3NJnTLwJYuhnSaDrP4LkNs0hROnIWnW1lGEJHcrzM,526
|
|
66
|
+
agent_knowledge/assets/templates/portfolio/.obsidian/app.json,sha256=FQ09dZuu6_3SllRWVATq6Qdeh7TNhOK7QXOZ-MC5Nug,91
|
|
67
|
+
agent_knowledge/assets/templates/portfolio/.obsidian/core-plugins.json,sha256=uFNP1AoeSuj8yI1HOxJtsj6hVEoqEjcItJ3kfN0BESc,81
|
|
68
|
+
agent_knowledge/assets/templates/project/.agent-project.yaml,sha256=6MwUCIHoEtJmv5AqICABtbHwL-sD96i3ugL7UmqEc7Q,967
|
|
69
|
+
agent_knowledge/assets/templates/project/.agentknowledgeignore,sha256=1JCTgoPIt4In-kDXndlYnPWJj0G2jjKaTYTYFcC8V7M,240
|
|
70
|
+
agent_knowledge/assets/templates/project/AGENTS.md,sha256=K9R3XmhTIOHry3k41QFMJD50v2ZPcEfkrVT6dp5YRpE,3632
|
|
71
|
+
agent_knowledge/assets/templates/project/gitignore.agent-knowledge,sha256=Ug1F1UN1tI23yYHN_cgRTz31PfC2ch7pnhvxeiBonss,509
|
|
72
|
+
agent_knowledge/assets/templates/project/agent-knowledge/STATUS.md,sha256=tJXGzBKta69FVoDFlVdW4k1NU4yC2Mn1EO5HNF5tRrM,958
|
|
73
|
+
agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/README.md,sha256=XF-w2MENwE-FfSfvmo3twr6KlIIQok52cvME6-K2XMM,497
|
|
74
|
+
agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/app.json,sha256=FQ09dZuu6_3SllRWVATq6Qdeh7TNhOK7QXOZ-MC5Nug,91
|
|
75
|
+
agent_knowledge/assets/templates/project/agent-knowledge/.obsidian/core-plugins.json,sha256=uFNP1AoeSuj8yI1HOxJtsj6hVEoqEjcItJ3kfN0BESc,81
|
|
76
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Evidence/README.md,sha256=A1IPk7y7KpecRQkd-VhLbGgyXa7DYfgQw_BT64_MKO8,759
|
|
77
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Evidence/imports/README.md,sha256=McFI-ugYmf09ff0IV66HltWK__MhL4f5wtaduyZvjUc,646
|
|
78
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Evidence/raw/README.md,sha256=_25ZxYPWOvNX4WILpt2qg_ZMcLXdb86LxRjSFJC5hqE,422
|
|
79
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Memory/MEMORY.md,sha256=Lj9h79KCJBNlkrNtpKqIEN9YdmRvjd95Bk7QCNKlT3M,744
|
|
80
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Memory/decisions/decisions.md,sha256=JqiXVAdfrOFwp2FqdJvIHjeO2HfxUmGj2cki6I025gY,443
|
|
81
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Outputs/README.md,sha256=iB-sdU9mL6Ek7onu0VvK09JtlzoiFgiTTFNlAZmrGF4,529
|
|
82
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Sessions/README.md,sha256=SeDss5OL8BYhyTecXhkypnIZmDmZqZ1Lahv0dUlqof0,337
|
|
83
|
+
agent_knowledge/assets/templates/project/agent-knowledge/Templates/README.md,sha256=tTQ9p-yOhdVxZOCWQojwYeRSc5ek6LQE0VzuS9ZdTSQ,352
|
|
84
|
+
agent_knowledge_cli-0.1.2.dist-info/METADATA,sha256=VuIA1lEziK5k7SARrofS5Mse_9UaHwsbgk_rS1toDR8,5289
|
|
85
|
+
agent_knowledge_cli-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
|
|
86
|
+
agent_knowledge_cli-0.1.2.dist-info/entry_points.txt,sha256=_MJERBuoeydY0U7oOHHExLknjwGRioFBl7H47Dz3Yc0,61
|
|
87
|
+
agent_knowledge_cli-0.1.2.dist-info/licenses/LICENSE,sha256=zKdV5IJV8FkkDkk-IRXQ0SB_tjJJmRmQvEMz8-TP9mk,1085
|
|
88
|
+
agent_knowledge_cli-0.1.2.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 agent-knowledge contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|