@llipe.com/dev-tasks 0.6.4 → 0.6.5
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.
- package/.claude/agents/developer.md +294 -0
- package/.claude/agents/github-ops.md +407 -0
- package/.claude/agents/housekeeping.md +109 -0
- package/.claude/agents/technical-writer.md +390 -0
- package/.claude/agents/ux-engineer.md +184 -0
- package/.claude/agents/verifier.md +276 -0
- package/.claude/commands/developer.md +272 -0
- package/.claude/commands/github-ops.md +10 -0
- package/.claude/commands/housekeeping.md +10 -0
- package/.claude/commands/planner.md +506 -0
- package/.claude/commands/product-engineer.md +263 -0
- package/.claude/commands/technical-writer.md +10 -0
- package/.claude/commands/ux-engineer.md +10 -0
- package/.claude/commands/verifier-audit.md +10 -0
- package/.claude/commands/verifier-design.md +10 -0
- package/.claude/hooks/git-guard.sh +95 -0
- package/.claude/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.claude/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.claude/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.claude/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.claude/skills/activity-generate-spec/SKILL.md +137 -0
- package/.claude/skills/activity-generate-stories/SKILL.md +243 -0
- package/.claude/skills/activity-init/SKILL.md +162 -0
- package/.claude/skills/activity-publish-github/SKILL.md +116 -0
- package/.claude/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.claude/skills/activity-refine/SKILL.md +236 -0
- package/.claude/skills/git-ops/SKILL.md +221 -0
- package/.claude/skills/implement/SKILL.md +129 -0
- package/.claude/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.claude/skills/memo-cli-usage/SKILL.md +144 -0
- package/.claude/skills/plan/SKILL.md +145 -0
- package/.claude/skills/webapp-mockup/SKILL.md +76 -0
- package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.github/agents/developer.agent.md +293 -0
- package/.github/agents/github-ops.agent.md +416 -0
- package/.github/agents/housekeeping.agent.md +109 -0
- package/.github/agents/planner.agent.md +496 -0
- package/.github/agents/product-engineer.agent.md +262 -0
- package/.github/agents/technical-writer.agent.md +389 -0
- package/.github/agents/ux-engineer.agent.md +183 -0
- package/.github/agents/verifier.agent.md +275 -0
- package/.github/instructions/domain/nextjs-pages-components.instructions.md +375 -0
- package/.github/instructions/implement.instructions.md +128 -0
- package/.github/instructions/plan.instructions.md +144 -0
- package/.github/prompts/developer-execute.prompt.md +13 -0
- package/.github/prompts/github-ops.prompt.md +16 -0
- package/.github/prompts/housekeeping.prompt.md +16 -0
- package/.github/prompts/planner-resume.prompt.md +13 -0
- package/.github/prompts/planner.prompt.md +18 -0
- package/.github/prompts/product-engineer-feature.prompt.md +21 -0
- package/.github/prompts/product-engineer-init.prompt.md +16 -0
- package/.github/prompts/product-engineer-issue.prompt.md +19 -0
- package/.github/prompts/technical-writer.prompt.md +21 -0
- package/.github/prompts/ux-engineer.prompt.md +14 -0
- package/.github/prompts/verifier-audit.prompt.md +33 -0
- package/.github/prompts/verifier-design.prompt.md +28 -0
- package/.github/skills/activity-contract-test-design/SKILL.md +117 -0
- package/.github/skills/activity-drift-reconciliation/SKILL.md +128 -0
- package/.github/skills/activity-e2e-test-design/SKILL.md +119 -0
- package/.github/skills/activity-edge-case-refinement/SKILL.md +141 -0
- package/.github/skills/activity-generate-spec/SKILL.md +132 -0
- package/.github/skills/activity-generate-stories/SKILL.md +238 -0
- package/.github/skills/activity-init/SKILL.md +157 -0
- package/.github/skills/activity-publish-github/SKILL.md +111 -0
- package/.github/skills/activity-random-test-tactics/SKILL.md +176 -0
- package/.github/skills/activity-refine/SKILL.md +231 -0
- package/.github/skills/git-ops/SKILL.md +216 -0
- package/.github/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.github/skills/memo-cli-usage/SKILL.md +144 -0
- package/.github/skills/webapp-mockup/SKILL.md +71 -0
- package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.kiro/agents/developer.md +305 -0
- package/.kiro/agents/github-ops.md +428 -0
- package/.kiro/agents/housekeeping.md +122 -0
- package/.kiro/agents/planner.md +530 -0
- package/.kiro/agents/product-engineer.md +294 -0
- package/.kiro/agents/technical-writer.md +408 -0
- package/.kiro/agents/ux-engineer.md +200 -0
- package/.kiro/agents/verifier.md +275 -0
- package/.kiro/hooks/git-guard.json +16 -0
- package/.kiro/hooks/scripts/git-guard.sh +116 -0
- package/.kiro/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.kiro/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.kiro/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.kiro/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.kiro/skills/activity-generate-spec/SKILL.md +137 -0
- package/.kiro/skills/activity-generate-stories/SKILL.md +243 -0
- package/.kiro/skills/activity-init/SKILL.md +162 -0
- package/.kiro/skills/activity-publish-github/SKILL.md +116 -0
- package/.kiro/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.kiro/skills/activity-refine/SKILL.md +236 -0
- package/.kiro/skills/git-ops/SKILL.md +221 -0
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.kiro/skills/memo-cli-usage/SKILL.md +144 -0
- package/.kiro/skills/webapp-mockup/SKILL.md +76 -0
- package/.kiro/steering/git-guard-notice.md +11 -0
- package/.kiro/steering/implement.md +129 -0
- package/.kiro/steering/nextjs-pages-components.md +376 -0
- package/.kiro/steering/plan.md +145 -0
- package/AGENTS.md +122 -0
- package/CHANGELOG.md +18 -2
- package/CLAUDE.md +94 -0
- package/README.md +6 -6
- package/dist/adapters/cli/extract-all.js +4 -4
- package/dist/adapters/cli/extract-component.d.ts +1 -1
- package/dist/adapters/cli/extract-component.js +4 -4
- package/dist/adapters/cli/parse-args.d.ts +1 -0
- package/dist/adapters/cli/parse-args.d.ts.map +1 -1
- package/dist/adapters/cli/parse-args.js +4 -0
- package/dist/adapters/cli/parse-args.js.map +1 -1
- package/dist/bin/dev-tasks.js +23 -9
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/bin/dt.js +3 -3
- package/dist/core/distribution/index.d.ts +5 -3
- package/dist/core/distribution/index.d.ts.map +1 -1
- package/dist/core/distribution/index.js +3 -2
- package/dist/core/distribution/index.js.map +1 -1
- package/dist/core/distribution/install.d.ts +20 -8
- package/dist/core/distribution/install.d.ts.map +1 -1
- package/dist/core/distribution/install.js +76 -36
- package/dist/core/distribution/install.js.map +1 -1
- package/dist/core/distribution/manifest.d.ts +25 -2
- package/dist/core/distribution/manifest.d.ts.map +1 -1
- package/dist/core/distribution/manifest.js +29 -2
- package/dist/core/distribution/manifest.js.map +1 -1
- package/dist/core/distribution/migrate.d.ts +6 -3
- package/dist/core/distribution/migrate.d.ts.map +1 -1
- package/dist/core/distribution/migrate.js +21 -19
- package/dist/core/distribution/migrate.js.map +1 -1
- package/dist/core/distribution/profiles.d.ts +30 -0
- package/dist/core/distribution/profiles.d.ts.map +1 -0
- package/dist/core/distribution/profiles.js +57 -0
- package/dist/core/distribution/profiles.js.map +1 -0
- package/dist/core/distribution/update.d.ts +6 -4
- package/dist/core/distribution/update.d.ts.map +1 -1
- package/dist/core/distribution/update.js +22 -22
- package/dist/core/distribution/update.js.map +1 -1
- package/dist/core/extract/component.d.ts +9 -9
- package/dist/core/extract/component.js +5 -5
- package/dist/core/extract/report.d.ts +1 -1
- package/dist/core/extract/report.js +1 -1
- package/package.json +15 -2
- package/skills/.gitkeep +0 -0
|
@@ -0,0 +1,798 @@
|
|
|
1
|
+
# memo-cli Full Reference
|
|
2
|
+
|
|
3
|
+
> This is the complete CLI documentation for `memo-cli`. For everyday usage patterns, see `SKILL.md`.
|
|
4
|
+
> Agents: read this file when performing setup, configuration, admin operations, or when you need detailed flag documentation.
|
|
5
|
+
|
|
6
|
+
# memo-cli Usage Skill
|
|
7
|
+
|
|
8
|
+
Teach AI agents (and human developers) how to operate **memo-cli** — the agent-first CLI for capturing and querying architectural decisions stored in a shared Qdrant vector database.
|
|
9
|
+
|
|
10
|
+
Use this skill whenever an agent needs to **read**, **write**, **search**, or **manage** decision entries in a repository that has `memo-cli` installed.
|
|
11
|
+
|
|
12
|
+
> **Portability:** This skill is self-contained. Copy the `memo-cli-usage/` folder into any repository's `.github/skills/` directory and reference it from that repo's `AGENTS.md` or skill registry.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Purpose
|
|
17
|
+
|
|
18
|
+
`memo-cli` is the **shared memory** that keeps agents coherent across time, sessions, and projects. It is not a log. It is not a changelog. It is a curated, searchable record of the decisions that shaped the codebase — written with enough precision that anyone (human or agent) arriving days, weeks, or months later can understand **what was decided, why, and what it affected**.
|
|
19
|
+
|
|
20
|
+
An agent that uses `memo-cli` well:
|
|
21
|
+
|
|
22
|
+
- Narrates its reasoning as it acts, not only at the end.
|
|
23
|
+
- Records the files it modifies and why those files were the right place.
|
|
24
|
+
- Explains configuration and architectural choices so future agents don't re-derive them.
|
|
25
|
+
- Tags entries consistently so discovery remains reliable across projects.
|
|
26
|
+
|
|
27
|
+
### Success Outcomes
|
|
28
|
+
|
|
29
|
+
Using memo-cli correctly SHOULD produce these outcomes:
|
|
30
|
+
|
|
31
|
+
- Faster planning and implementation by reusing prior constraints and decisions.
|
|
32
|
+
- Consistent execution across agents and sessions.
|
|
33
|
+
- Auditable traceability from decision to issue/story, files, and commit evidence.
|
|
34
|
+
- Better cross-repo contract safety when `--scope related` is used intentionally.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Entry Purposes and Scope
|
|
39
|
+
|
|
40
|
+
Every write MUST have one clear purpose. Do not combine multiple purposes into one long entry.
|
|
41
|
+
|
|
42
|
+
| Purpose | What it captures | Entry Type | Required lifecycle tag |
|
|
43
|
+
| --------------------- | ---------------------------------------------------- | ------------------- | ---------------------- |
|
|
44
|
+
| Intent | Planned approach, constraints, expected impact | `decision` | `intent` |
|
|
45
|
+
| Outcome | Delivered behavior and validation evidence | `decision` | `outcome` |
|
|
46
|
+
| Durable architecture | Long-lived technical decisions and trade-offs | `decision` | `decision` |
|
|
47
|
+
| Integration contract | Cross-boundary assumptions and compatibility details | `integration_point` | `contract` |
|
|
48
|
+
| Structural convention | Module boundaries and naming/layout rules | `structure` | `structure` |
|
|
49
|
+
|
|
50
|
+
Write only reusable knowledge. Do not write routine activity noise that is already obvious from a diff.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## When to Write to memo-cli
|
|
55
|
+
|
|
56
|
+
Write a memo entry **during** or **immediately after** any of these moments:
|
|
57
|
+
|
|
58
|
+
| Trigger | Entry Type |
|
|
59
|
+
| -------------------------------------------------------------------------- | ------------------------ |
|
|
60
|
+
| Choosing a library, framework, or service | `decision` |
|
|
61
|
+
| Choosing how to structure a module or data model | `decision` / `structure` |
|
|
62
|
+
| Changing a config file and explaining why | `decision` |
|
|
63
|
+
| Identifying or formalizing a cross-service contract | `integration_point` |
|
|
64
|
+
| Modifying critical files (entry points, core abstractions, schema) | `decision` |
|
|
65
|
+
| Discovering a constraint (API limit, platform quirk, security requirement) | `decision` |
|
|
66
|
+
| Resolving a conflict between two approaches | `decision` |
|
|
67
|
+
| Establishing a naming or layout convention | `structure` |
|
|
68
|
+
| Starting work on a story or task (intent entry) | `decision` |
|
|
69
|
+
| Completing a story or task (outcome entry) | `decision` |
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## When to Search memo-cli
|
|
74
|
+
|
|
75
|
+
Search **before** taking action, not only when stuck:
|
|
76
|
+
|
|
77
|
+
| Situation | Command |
|
|
78
|
+
| ---------------------------------------------- | ----------------------------------------------------- |
|
|
79
|
+
| Starting a session — restore context | `memo list --limit 20 --json` |
|
|
80
|
+
| Normalize vocabulary before writing | `memo tags list --sort frequency --json` |
|
|
81
|
+
| Before making a design choice | `memo search "<topic>" --json` |
|
|
82
|
+
| Before touching a file you haven't seen before | `memo search "<filename or module name>" --json` |
|
|
83
|
+
| Evaluating whether to add a dependency | `memo search "<library name>" --scope related --json` |
|
|
84
|
+
| Onboarding to an unfamiliar repo | `memo inspect --json` then `memo list --json` |
|
|
85
|
+
|
|
86
|
+
### Required Read Sequence
|
|
87
|
+
|
|
88
|
+
At session start, run reads in this exact order:
|
|
89
|
+
|
|
90
|
+
1. `memo setup validate`
|
|
91
|
+
2. `memo list --limit 20 --json`
|
|
92
|
+
3. `memo tags list --sort frequency --json`
|
|
93
|
+
4. `memo search "<current issue/story/title>" --limit 10 --json`
|
|
94
|
+
5. `memo search "<key contract or dependency>" --scope related --limit 5 --json` (when boundary impact is expected)
|
|
95
|
+
|
|
96
|
+
Before coding or planning, synthesize findings in 4 bullets:
|
|
97
|
+
|
|
98
|
+
- Constraints to preserve
|
|
99
|
+
- Rejected alternatives to avoid
|
|
100
|
+
- Contracts/boundaries that must remain stable
|
|
101
|
+
- Sensitive files/modules to treat carefully
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Minimum Entry Schema
|
|
106
|
+
|
|
107
|
+
All entries SHOULD include these fields when applicable:
|
|
108
|
+
|
|
109
|
+
- Scope: issue/story identifier (`issue-<n>` or `story-<id>`)
|
|
110
|
+
- Context: what changed and why now
|
|
111
|
+
- Decision/Delivery: what was chosen or implemented
|
|
112
|
+
- Impact: downstream behavior or contracts affected
|
|
113
|
+
- Evidence: commit SHA and key files (`outcome` required)
|
|
114
|
+
|
|
115
|
+
Additional requirements by purpose:
|
|
116
|
+
|
|
117
|
+
- Intent entries MUST include constraints/non-goals and expected files.
|
|
118
|
+
- Outcome entries MUST include AC coverage and quality gate status (`test`, `lint`, `format:check`, `typecheck`, `audit`).
|
|
119
|
+
- Contract entries MUST include producer, consumer, validation rules, and failure behavior.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Tag Taxonomy Standard
|
|
124
|
+
|
|
125
|
+
Tags MUST be kebab-case and ordered in these layers:
|
|
126
|
+
|
|
127
|
+
1. Domain tag (for example: `auth`, `tenant`, `ingestion`, `docs`)
|
|
128
|
+
2. Work-item tag (`issue-113`, `story-s003`)
|
|
129
|
+
3. Lifecycle tag (`intent`, `outcome`, `decision`, `contract`, `structure`)
|
|
130
|
+
4. Impact/quality tag (`security`, `migration`, `gates-pass`, `docs-drift-fixed`)
|
|
131
|
+
5. Optional boundary tag (`api`, `middleware`, `cross-repo`)
|
|
132
|
+
|
|
133
|
+
Use 4-5 tags whenever possible. Reuse existing tags from `memo tags list`.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Prerequisites
|
|
138
|
+
|
|
139
|
+
### Environment Variables
|
|
140
|
+
|
|
141
|
+
The following variables **MUST** be set before any `memo` command will work:
|
|
142
|
+
|
|
143
|
+
| Variable | Purpose | Example |
|
|
144
|
+
| --------------------- | ------------------------- | ----------------------- |
|
|
145
|
+
| `QDRANT_URL` | Qdrant instance endpoint | `http://localhost:6333` |
|
|
146
|
+
| `QDRANT_API_KEY` | API key (empty for local) | `""` or a cloud key |
|
|
147
|
+
| `EMBEDDINGS_PROVIDER` | Embedding backend | `openai` |
|
|
148
|
+
| `EMBEDDINGS_API_KEY` | Provider secret key | `sk-...` |
|
|
149
|
+
|
|
150
|
+
> **Tip:** Store these in a `.env` file at the repository root. `memo-cli` loads it automatically via `dotenv`.
|
|
151
|
+
|
|
152
|
+
### Repository Configuration
|
|
153
|
+
|
|
154
|
+
A `memo.config.json` **MUST** exist at the repository root. Create one with:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
memo setup init --repo <repo-name> --org <org-name> --domain <domain> [--relates-to repo1,repo2]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Verify it at any time:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
memo setup validate # exit 0 = valid
|
|
164
|
+
memo setup show # print effective config
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Core Concepts
|
|
170
|
+
|
|
171
|
+
### `repo` — Repository Identity
|
|
172
|
+
|
|
173
|
+
`repo` is the **name of the codebase** this entry belongs to. It is set in `memo.config.json` and defaults into every `memo write` call automatically. Use the kebab-case name of the Git repository (e.g., `memo-cli`, `auth-service`, `api-gateway`).
|
|
174
|
+
|
|
175
|
+
**Why it matters:** Every entry is scoped to a repo. `memo search` and `memo list` filter by your current repo by default, so entries from other repos don't pollute your results unless you explicitly request them with `--scope related`.
|
|
176
|
+
|
|
177
|
+
**Rule:** Use the repo's canonical name — the one that appears in the GitHub URL. Don't abbreviate or alias it.
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
### `org` — Organization
|
|
182
|
+
|
|
183
|
+
`org` is the **owner or organization** that the repository belongs to. In GitHub terms, this is the account or org username (e.g., `llipe`, `acme-corp`, `my-team`).
|
|
184
|
+
|
|
185
|
+
**Why it matters:** `org` groups related repositories under a common owner. It enables cross-repo queries scoped to a single organization — e.g., finding all decisions made under `acme-corp` across all its services.
|
|
186
|
+
|
|
187
|
+
**Rule:** Use the GitHub organization or user handle, kebab-case. All repos under the same team should share the same `org` value.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
### `domain` — Product or Functional Area
|
|
192
|
+
|
|
193
|
+
`domain` describes the **product area or functional concern** that this repository serves (e.g., `auth`, `payments`, `infra`, `ai`, `search`, `notifications`). It is broader than a repository — multiple repos can share the same domain.
|
|
194
|
+
|
|
195
|
+
**Why it matters:** Domain is a cross-cutting label that lets you query decisions across all repos in a functional area. For example, all `auth`-domain decisions across `auth-service`, `api-gateway`, and `user-service` can be retrieved together.
|
|
196
|
+
|
|
197
|
+
**How to choose:**
|
|
198
|
+
|
|
199
|
+
- Use the business or technical capability, not the team name.
|
|
200
|
+
- Keep it stable — domains change less often than repos.
|
|
201
|
+
- Examples: `auth`, `billing`, `data-pipeline`, `mobile`, `platform`, `ai`, `infra`, `developer-tools`.
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
### `relates_to` — Connected Repositories
|
|
206
|
+
|
|
207
|
+
`relates_to` is an **explicit list of other repository names** that this repo has a meaningful relationship with — shared contracts, shared schemas, upstream/downstream dependencies, or simply repos that an agent often works across together.
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"relates_to": ["auth-service", "api-gateway", "shared-lib"]
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
**Why it matters:** Setting `relates_to` enables `--scope related` queries, which search entries across this repo **and** all listed repos simultaneously. This is how agents and developers get cross-service context without switching repositories.
|
|
216
|
+
|
|
217
|
+
**When to add a repo to `relates_to`:**
|
|
218
|
+
|
|
219
|
+
- This repo consumes an API or event contract that the other repo owns.
|
|
220
|
+
- Decisions in the other repo often directly constrain decisions in this one.
|
|
221
|
+
- You regularly need to cross-reference both repos during feature work.
|
|
222
|
+
- They share a data model or schema.
|
|
223
|
+
|
|
224
|
+
**Rule:** Keep `relates_to` intentional — list real dependencies, not every repo in the org. A bloated list degrades search signal.
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
### Entry Types
|
|
229
|
+
|
|
230
|
+
| Type | When to use |
|
|
231
|
+
| ------------------- | ------------------------------------------------------------------------- |
|
|
232
|
+
| `decision` | Architectural or design choices ("We chose Postgres over Mongo because…") |
|
|
233
|
+
| `integration_point` | Cross-service contracts, API boundaries, shared schemas |
|
|
234
|
+
| `structure` | Folder layout, module boundaries, naming conventions |
|
|
235
|
+
|
|
236
|
+
### Source
|
|
237
|
+
|
|
238
|
+
| Value | Meaning |
|
|
239
|
+
| -------- | -------------------------------------------------------------- |
|
|
240
|
+
| `agent` | Written by an AI agent (default when `defaults.source` is set) |
|
|
241
|
+
| `manual` | Written by a human developer |
|
|
242
|
+
|
|
243
|
+
### Scoping
|
|
244
|
+
|
|
245
|
+
Every entry belongs to a **repo**, **org**, and **domain** (all kebab-case). Queries default to the current repo context from `memo.config.json`.
|
|
246
|
+
|
|
247
|
+
- `--scope repo` — Only entries for the current repository.
|
|
248
|
+
- `--scope related` — Current repository + all repos listed in `relates_to`.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Command Reference
|
|
253
|
+
|
|
254
|
+
### `memo write` — Record a Decision
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
memo write \
|
|
258
|
+
--rationale "Chose JWT over session cookies for stateless auth across services" \
|
|
259
|
+
--tags "auth,jwt,stateless" \
|
|
260
|
+
--entry-type decision \
|
|
261
|
+
--source agent \
|
|
262
|
+
--json
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
**Required flags:**
|
|
266
|
+
|
|
267
|
+
- `--rationale` — The decision text (1–5 000 chars).
|
|
268
|
+
- `--tags` — 2–5 comma-separated kebab-case tags.
|
|
269
|
+
|
|
270
|
+
**Optional flags:**
|
|
271
|
+
|
|
272
|
+
- `--entry-type` — `decision` (default) | `integration_point` | `structure`
|
|
273
|
+
- `--source` — `agent` | `manual` (falls back to config default)
|
|
274
|
+
- `--commit` — Git commit SHA for traceability
|
|
275
|
+
- `--story` — Story or task ID
|
|
276
|
+
- `--files` — Comma-separated file paths touched by the decision
|
|
277
|
+
- `--relates-to` — Related repo names
|
|
278
|
+
- `--on-duplicate` — `consolidate` | `update` | `replace` | `create-new`
|
|
279
|
+
- `--json` — Machine-readable output (**always use in agent mode**)
|
|
280
|
+
|
|
281
|
+
**Duplicate handling:**
|
|
282
|
+
When memo detects a duplicate (same `repo + commit + story + entry_type + source`), interactive mode prompts for resolution. In `--json` mode you **MUST** supply `--on-duplicate` or the command will fail.
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
### `memo search` — Semantic Search
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
memo search "rate limiting strategy" --limit 5 --json
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Natural-language vector search over decision entries.
|
|
293
|
+
|
|
294
|
+
**Optional flags:**
|
|
295
|
+
|
|
296
|
+
- `--scope` — `repo` (default) | `related`
|
|
297
|
+
- `--tags` — Comma-separated filter (AND logic)
|
|
298
|
+
- `--entry-type` — Filter by type
|
|
299
|
+
- `--source` — Filter by source
|
|
300
|
+
- `--limit` — Max results (default 10)
|
|
301
|
+
- `--json` — Machine-readable output
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
### `memo list` — Chronological Browse
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
memo list --limit 20 --json
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Most-recent-first listing with optional date range.
|
|
312
|
+
|
|
313
|
+
**Optional flags:**
|
|
314
|
+
|
|
315
|
+
- `--scope`, `--tags`, `--entry-type`, `--source` — Same as search
|
|
316
|
+
- `--from` / `--to` — ISO 8601 date boundaries
|
|
317
|
+
- `--limit` — Max results (default 20)
|
|
318
|
+
- `--json` — Machine-readable output
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
### `memo tags list` — Discover Tags
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
memo tags list --sort frequency --json
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Shows all unique tags with entry counts.
|
|
329
|
+
|
|
330
|
+
**Optional flags:**
|
|
331
|
+
|
|
332
|
+
- `--scope` — `repo` | `related`
|
|
333
|
+
- `--sort` — `alpha` (default) | `frequency`
|
|
334
|
+
- `--json` — Machine-readable output
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
### `memo inspect` — Global Facet Discovery
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
memo inspect --json
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Lists all organizations, repositories, and domains across the entire knowledge base (ignores repo scope). Useful for onboarding and cross-team exploration.
|
|
345
|
+
|
|
346
|
+
**Optional flags:**
|
|
347
|
+
|
|
348
|
+
- `--orgs` / `--repos` / `--domains` — Show only one facet
|
|
349
|
+
- `--json` — Machine-readable output
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
### `memo delete` — Remove Entries
|
|
354
|
+
|
|
355
|
+
**Single entry:**
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
memo delete --id <uuid> --json
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
**Bulk (interactive only — blocked in `--json` mode for safety):**
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
memo delete --all-by-repo <repo-name> --yes
|
|
365
|
+
memo delete --all-by-org <org-name> --yes
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
Exactly one of `--id`, `--all-by-repo`, or `--all-by-org` is required.
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
## Agent Workflows
|
|
373
|
+
|
|
374
|
+
### Starting a Session — Restore Context
|
|
375
|
+
|
|
376
|
+
At the **beginning of every session**, run this sequence before writing a single line of code:
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
# 1. Confirm config is valid
|
|
380
|
+
memo setup validate
|
|
381
|
+
|
|
382
|
+
# 2. Discover what repos/orgs/domains exist
|
|
383
|
+
memo inspect --json
|
|
384
|
+
|
|
385
|
+
# 3. Review recent decisions for this repo
|
|
386
|
+
memo list --limit 20 --json
|
|
387
|
+
|
|
388
|
+
# 4. Check the established tag vocabulary
|
|
389
|
+
memo tags list --sort frequency --json
|
|
390
|
+
|
|
391
|
+
# 5. Search for context relevant to the current task
|
|
392
|
+
memo search "<current task or feature description>" --limit 10 --json
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
Read the results before proceeding. Prior entries may contain constraints, preferred patterns, or rejected alternatives that directly affect how you should approach the current task.
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
### Recording Decisions — As You Work, Not Only at the End
|
|
400
|
+
|
|
401
|
+
Write a memo entry **at the moment you make a decision**, not as a post-hoc summary. This preserves the full reasoning before context is lost.
|
|
402
|
+
|
|
403
|
+
**Template:**
|
|
404
|
+
|
|
405
|
+
```bash
|
|
406
|
+
memo write \
|
|
407
|
+
--rationale "CONTEXT. DECISION. RATIONALE." \
|
|
408
|
+
--tags "tag1,tag2,tag3" \
|
|
409
|
+
--entry-type decision \
|
|
410
|
+
--source agent \
|
|
411
|
+
--commit "$(git rev-parse HEAD)" \
|
|
412
|
+
--story "ISSUE-42" \
|
|
413
|
+
--files "path/to/file1.ts,path/to/file2.ts" \
|
|
414
|
+
--json
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
The `--rationale` field is the most important field. See **Writing Quality** below.
|
|
418
|
+
|
|
419
|
+
---
|
|
420
|
+
|
|
421
|
+
### Recording File Changes — Explain the Why
|
|
422
|
+
|
|
423
|
+
When modifying a significant file (entry point, core abstraction, schema, config), record what changed and why:
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
memo write \
|
|
427
|
+
--rationale "Modified src/lib/config.ts to add schema_version validation. The config loader previously accepted any object; adding Zod validation ensures CLI commands fail fast on malformed configs rather than producing silent errors downstream." \
|
|
428
|
+
--tags "config,validation,config-ts,error-handling" \
|
|
429
|
+
--entry-type decision \
|
|
430
|
+
--source agent \
|
|
431
|
+
--commit "$(git rev-parse HEAD)" \
|
|
432
|
+
--files "src/lib/config.ts,src/types/config.ts" \
|
|
433
|
+
--json
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
|
|
438
|
+
### Recording Configuration Decisions
|
|
439
|
+
|
|
440
|
+
Configuration decisions are especially important to preserve — they often appear opaque later with no obvious rationale in the code.
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
memo write \
|
|
444
|
+
--rationale "Set QDRANT_COLLECTION_NAME to 'decisions' permanently rather than making it configurable. A single collection per deployment simplifies queries and access control. Multi-tenancy is achieved via repo/org payload fields, not separate collections. Reconsidering this would require a data migration." \
|
|
445
|
+
--tags "qdrant,config,multi-tenancy,collection-design" \
|
|
446
|
+
--entry-type decision \
|
|
447
|
+
--source agent \
|
|
448
|
+
--json
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
Configuration decisions to always record:
|
|
452
|
+
|
|
453
|
+
- Environment variable semantics (what the value controls, valid ranges, defaults)
|
|
454
|
+
- Feature flags and their trigger conditions
|
|
455
|
+
- Schema versions and migration policies
|
|
456
|
+
- Storage layout choices (collection names, index strategies, partitioning)
|
|
457
|
+
- Security-related configuration (TLS, auth, CORS, rate limits)
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
### Intent Entry — Narrate Before Acting
|
|
462
|
+
|
|
463
|
+
For significant tasks, write an **intent entry** before starting implementation. This creates a checkpoint that future sessions can find, and anchors the rationale for every decision that follows.
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
memo write \
|
|
467
|
+
--rationale "Starting implementation of story ISSUE-37: safe delete command. Approach: add a --yes flag for non-interactive confirmation, block --json with bulk delete flags (safety guard for agents), preview affected entries before deletion. No soft-delete; permanent removal via Qdrant point deletion. This matches the existing write/search command pattern." \
|
|
468
|
+
--tags "delete,safety,issue-37,intent" \
|
|
469
|
+
--entry-type decision \
|
|
470
|
+
--source agent \
|
|
471
|
+
--story "ISSUE-37" \
|
|
472
|
+
--json
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
### Outcome Entry — Summarize After Completing
|
|
478
|
+
|
|
479
|
+
When finishing a task, write an **outcome entry** that captures what actually happened vs. what was intended:
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
memo write \
|
|
483
|
+
--rationale "Completed ISSUE-37 safe delete command. Shipped: --id single delete, --all-by-repo and --all-by-org bulk delete (interactive only), --yes to skip confirm, preview before deletion. Deviation from intent: bulk delete also disallowed with --json (not just flagged) after discovering Qdrant batch delete has no confirmation step. Modified: src/commands/delete.ts (new), tests/unit/commands/delete.test.ts (new)." \
|
|
484
|
+
--tags "delete,safety,issue-37,outcome" \
|
|
485
|
+
--entry-type decision \
|
|
486
|
+
--source agent \
|
|
487
|
+
--story "ISSUE-37" \
|
|
488
|
+
--files "src/commands/delete.ts,tests/unit/commands/delete.test.ts" \
|
|
489
|
+
--json
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
---
|
|
493
|
+
|
|
494
|
+
## Writing Quality
|
|
495
|
+
|
|
496
|
+
The `--rationale` field must be **precise enough that a different developer or agent — with no prior context — can understand what was decided, why, and what it affects.** A good entry answers three questions:
|
|
497
|
+
|
|
498
|
+
1. **Context** — What is the situation, constraint, or problem?
|
|
499
|
+
2. **Decision** — What was chosen or done?
|
|
500
|
+
3. **Rationale** — Why this choice over the alternatives?
|
|
501
|
+
|
|
502
|
+
### Good vs. Bad Examples
|
|
503
|
+
|
|
504
|
+
**Too vague — useless to a future reader:**
|
|
505
|
+
|
|
506
|
+
> "Updated auth to use JWT."
|
|
507
|
+
|
|
508
|
+
**Precise — useful across sessions and developers:**
|
|
509
|
+
|
|
510
|
+
> "Switched authentication from server-side sessions to JWT (HS256, 15-min access + 7-day refresh). Sessions required sticky routing which is incompatible with the planned horizontal scaling. JWTs are stateless — any instance can validate without a shared session store. Trade-off: revocation requires a Redis blacklist (added to ISSUE-51 backlog). Files: src/auth/jwt.ts, src/middleware/auth.ts."
|
|
511
|
+
|
|
512
|
+
---
|
|
513
|
+
|
|
514
|
+
**Too vague:**
|
|
515
|
+
|
|
516
|
+
> "Changed config validation."
|
|
517
|
+
|
|
518
|
+
**Precise:**
|
|
519
|
+
|
|
520
|
+
> "Added Zod validation to memo.config.json loader (src/lib/config.ts). Previously the code trusted the file's shape; malformed configs caused cryptic runtime errors deep in Qdrant queries. Now the CLI fails immediately at startup with a structured error message. This is the single place config is read — no other validation needed."
|
|
521
|
+
|
|
522
|
+
---
|
|
523
|
+
|
|
524
|
+
**Too vague:**
|
|
525
|
+
|
|
526
|
+
> "Used Redis for caching."
|
|
527
|
+
|
|
528
|
+
**Precise:**
|
|
529
|
+
|
|
530
|
+
> "Chose Redis (via ioredis) over in-process LRU cache for rate-limit counters. In-process cache doesn't survive pod restarts and is not shared across replicas. Redis TTL natively aligns with the sliding window algorithm. Accepted dependency: Redis must be available in all environments. Config: REDIS_URL env var, no auth in dev, TLS required in prod."
|
|
531
|
+
|
|
532
|
+
---
|
|
533
|
+
|
|
534
|
+
### Structural Rule
|
|
535
|
+
|
|
536
|
+
Write `--rationale` as a single coherent paragraph (or 2-3 short sentences). **Avoid bullet points** in the rationale field — they fragment reasoning and lose connective logic. Save structure for tags.
|
|
537
|
+
|
|
538
|
+
Minimum viable rationale: **context sentence + decision sentence + why sentence**.
|
|
539
|
+
|
|
540
|
+
---
|
|
541
|
+
|
|
542
|
+
## Tag Strategy
|
|
543
|
+
|
|
544
|
+
Tags are the primary way to discover entries. Good tagging makes the difference between a searchable knowledge base and an unsearchable archive.
|
|
545
|
+
|
|
546
|
+
### Tag Layers
|
|
547
|
+
|
|
548
|
+
Apply tags across **multiple layers** simultaneously:
|
|
549
|
+
|
|
550
|
+
| Layer | Purpose | Examples |
|
|
551
|
+
| ------------------ | ----------------------- | ------------------------------------------------------ |
|
|
552
|
+
| **Domain/feature** | What area of the system | `auth`, `rate-limiting`, `config`, `delete`, `storage` |
|
|
553
|
+
| **Technology** | What tech is involved | `qdrant`, `redis`, `openai`, `zod`, `jwt` |
|
|
554
|
+
| **Entry nature** | What kind of change | `intent`, `outcome`, `constraint`, `trade-off`, `adr` |
|
|
555
|
+
| **Story/task ref** | Traceability | `issue-37`, `story-s003`, `prd-001` |
|
|
556
|
+
| **Scope** | How broad the impact | `cross-repo`, `breaking-change`, `config-change` |
|
|
557
|
+
|
|
558
|
+
Every write SHOULD include tags from at least **2–3 layers**.
|
|
559
|
+
|
|
560
|
+
### Before Inventing a Tag — Check What Exists
|
|
561
|
+
|
|
562
|
+
```bash
|
|
563
|
+
memo tags list --sort frequency --json
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
Re-use existing tags whenever possible. Consistent vocabulary is what allows `memo search` to surface related entries from weeks ago or from a different repository.
|
|
567
|
+
|
|
568
|
+
### Tag Naming Rules
|
|
569
|
+
|
|
570
|
+
- Kebab-case only: `rate-limiting`, not `rateLimiting` or `rate_limiting`.
|
|
571
|
+
- Prefer specific over generic: `qdrant-collection` over `database`.
|
|
572
|
+
- For story/task refs: `issue-37`, `story-s003` (numeric, no spaces).
|
|
573
|
+
- Session markers: `intent` (beginning of task) and `outcome` (completion).
|
|
574
|
+
- For cross-cutting concerns: `breaking-change`, `security`, `performance`, `config-change`.
|
|
575
|
+
|
|
576
|
+
### Tag Examples by Scenario
|
|
577
|
+
|
|
578
|
+
**Architectural decision on storage:**
|
|
579
|
+
|
|
580
|
+
```
|
|
581
|
+
qdrant,collection-design,multi-tenancy,decision,adr
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
**Config change:**
|
|
585
|
+
|
|
586
|
+
```
|
|
587
|
+
config,env-vars,config-change,issue-42
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
**Integration contract between two services:**
|
|
591
|
+
|
|
592
|
+
```
|
|
593
|
+
api-contract,auth-service,cross-repo,integration-point,breaking-change
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
**Starting a new feature (intent):**
|
|
597
|
+
|
|
598
|
+
```
|
|
599
|
+
delete-command,safety,issue-37,intent
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
**Completing a feature (outcome):**
|
|
603
|
+
|
|
604
|
+
```
|
|
605
|
+
delete-command,safety,issue-37,outcome
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
**Performance trade-off:**
|
|
609
|
+
|
|
610
|
+
```
|
|
611
|
+
embeddings,openai,performance,trade-off,caching
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
---
|
|
615
|
+
|
|
616
|
+
## Multi-Developer & Cross-Session Context
|
|
617
|
+
|
|
618
|
+
`memo-cli` is designed so that **every agent and every developer shares the same decision history**. This is what enables continuity across days, team rotations, and parallel workstreams.
|
|
619
|
+
|
|
620
|
+
### Shared Knowledge Base
|
|
621
|
+
|
|
622
|
+
All entries are stored in a shared Qdrant instance. When Developer A (or Agent A) records a decision, Developer B can immediately find it via `memo search`. There is no per-user silo.
|
|
623
|
+
|
|
624
|
+
### Cross-Repository Visibility
|
|
625
|
+
|
|
626
|
+
Use `--scope related` to query across connected repositories:
|
|
627
|
+
|
|
628
|
+
```bash
|
|
629
|
+
memo search "auth contract" --scope related --json
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
This is critical for:
|
|
633
|
+
|
|
634
|
+
- Microservice architectures where contracts span repos.
|
|
635
|
+
- Agent workflows that touch multiple repositories in sequence.
|
|
636
|
+
- Detecting when a decision in one repo contradicts a constraint in another.
|
|
637
|
+
|
|
638
|
+
Configure related repos in `memo.config.json`:
|
|
639
|
+
|
|
640
|
+
```json
|
|
641
|
+
{
|
|
642
|
+
"relates_to": ["auth-service", "api-gateway", "shared-lib"]
|
|
643
|
+
}
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
### Session Continuity for Agents
|
|
647
|
+
|
|
648
|
+
Agents are stateless between sessions. To maintain continuity:
|
|
649
|
+
|
|
650
|
+
1. **Start every session** with `memo list` and `memo search` — always.
|
|
651
|
+
2. **Write an intent entry** before starting significant work.
|
|
652
|
+
3. **Write as you decide**, not as a batch at the end.
|
|
653
|
+
4. **Write an outcome entry** when completing a task, including any deviations from intent.
|
|
654
|
+
5. **Tag consistently** — check `memo tags list` before picking tags.
|
|
655
|
+
|
|
656
|
+
### Multi-Day Work Pattern
|
|
657
|
+
|
|
658
|
+
For work that spans multiple days:
|
|
659
|
+
|
|
660
|
+
- **Day 1 end**: Write an outcome entry with current state, what's done, what's next, any open questions.
|
|
661
|
+
- **Day 2 start**: `memo search "<task name or issue number>" --json` to restore exact context.
|
|
662
|
+
- The tags `intent` and `outcome` combined with a story tag (e.g., `issue-37`) make the full arc of a feature retrievable as a timeline.
|
|
663
|
+
|
|
664
|
+
### What to Record vs. What to Skip
|
|
665
|
+
|
|
666
|
+
| Record | Skip |
|
|
667
|
+
| --------------------------------------------- | ----------------------------------------------------------- |
|
|
668
|
+
| Architectural choices and their rationale | Trivial implementation details (variable names, formatting) |
|
|
669
|
+
| Technology selections with trade-off analysis | Routine bug fixes with no design impact |
|
|
670
|
+
| Configuration changes that affect behavior | Code style choices (use linters) |
|
|
671
|
+
| API contracts and integration boundaries | Dependency version bumps (use lockfile) |
|
|
672
|
+
| Security-sensitive design choices | Temporary workarounds expected to be removed within hours |
|
|
673
|
+
| Performance trade-offs and their context | Generated code |
|
|
674
|
+
| Rejected alternatives and why | CI/build configuration (use config files) |
|
|
675
|
+
| Constraints discovered during implementation | Debugging steps |
|
|
676
|
+
|
|
677
|
+
---
|
|
678
|
+
|
|
679
|
+
## Memory Scopes (IDE / Agent Memory vs. memo-cli)
|
|
680
|
+
|
|
681
|
+
Many agent runtimes (e.g., VS Code Copilot) have a built-in memory system alongside `memo-cli`. Understanding when to use each prevents both redundancy and gaps.
|
|
682
|
+
|
|
683
|
+
| Scope | Where | Persistence | Use For |
|
|
684
|
+
| --------------------- | ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
685
|
+
| **User memory** | `/memories/` | All workspaces, all sessions | Personal preferences, debugging patterns, general agent insights |
|
|
686
|
+
| **Session memory** | `/memories/session/` | Current conversation only | Scratch notes, in-progress state, temporary checklists |
|
|
687
|
+
| **Repository memory** | `/memories/repo/` | Current workspace | Repo gotchas, build commands, local conventions — fast-access notes for this repo |
|
|
688
|
+
| **memo-cli** | Qdrant (shared remote) | Permanent, shared across all people and agents | Architectural decisions, integration contracts, structural choices, configuration rationale |
|
|
689
|
+
|
|
690
|
+
### Decision Tree: Where Does This Information Belong?
|
|
691
|
+
|
|
692
|
+
```
|
|
693
|
+
Is it a decision, rationale, constraint, contract, or config choice?
|
|
694
|
+
└─ YES → memo write (it belongs to the shared knowledge base)
|
|
695
|
+
|
|
696
|
+
Is it a repo-specific gotcha or quick operational fact?
|
|
697
|
+
└─ YES → /memories/repo/ (and also memo write if it reflects a real design choice)
|
|
698
|
+
|
|
699
|
+
Is it a personal preference or general agent pattern?
|
|
700
|
+
└─ YES → /memories/ (user memory)
|
|
701
|
+
|
|
702
|
+
Is it temporary context that only matters for the current session?
|
|
703
|
+
└─ YES → /memories/session/
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
**Key principle:** If the information would help a _different_ developer or agent working in the same codebase — even a year from now — it belongs in `memo-cli`.
|
|
707
|
+
|
|
708
|
+
---
|
|
709
|
+
|
|
710
|
+
## Safe Operation Guardrails
|
|
711
|
+
|
|
712
|
+
### Non-Destructive Defaults
|
|
713
|
+
|
|
714
|
+
- `memo delete` requires confirmation by default. Use `--yes` to skip only when you are certain.
|
|
715
|
+
- Bulk delete (`--all-by-repo`, `--all-by-org`) is **blocked in `--json` mode** as a safety guard against accidental mass deletion by agents.
|
|
716
|
+
- `memo write` detects duplicates and prompts for resolution rather than silently overwriting.
|
|
717
|
+
|
|
718
|
+
### Agent Mode (`--json`)
|
|
719
|
+
|
|
720
|
+
Agents **SHOULD** always pass `--json` for predictable, parseable output. Key behaviors in JSON mode:
|
|
721
|
+
|
|
722
|
+
- All output is structured JSON on stdout.
|
|
723
|
+
- Errors produce JSON error objects to stderr.
|
|
724
|
+
- Interactive prompts are suppressed — flags must supply all decisions.
|
|
725
|
+
- `--on-duplicate` is required when a duplicate is detected.
|
|
726
|
+
- Bulk delete is prohibited.
|
|
727
|
+
|
|
728
|
+
### Validation Before Writing
|
|
729
|
+
|
|
730
|
+
Before `memo write`, agents SHOULD:
|
|
731
|
+
|
|
732
|
+
1. Verify `memo setup validate` passes.
|
|
733
|
+
2. Confirm tags are kebab-case (lowercase, hyphens only).
|
|
734
|
+
3. Ensure rationale is meaningful (not placeholder text).
|
|
735
|
+
4. Check for duplicates with `memo search` first.
|
|
736
|
+
|
|
737
|
+
### Error Handling
|
|
738
|
+
|
|
739
|
+
All `memo` commands exit with:
|
|
740
|
+
|
|
741
|
+
- **0** — Success
|
|
742
|
+
- **1** — Validation or user error (bad flags, invalid config)
|
|
743
|
+
- **2** — Unexpected/infrastructure error (Qdrant down, embedding API failure)
|
|
744
|
+
|
|
745
|
+
When a command fails:
|
|
746
|
+
|
|
747
|
+
1. Read the error code and message from stderr.
|
|
748
|
+
2. For exit code 1: fix the input and retry.
|
|
749
|
+
3. For exit code 2: check connectivity (`QDRANT_URL`) and API keys before retrying.
|
|
750
|
+
|
|
751
|
+
### Environment Variable Safety
|
|
752
|
+
|
|
753
|
+
- **Never** log or output `EMBEDDINGS_API_KEY` or `QDRANT_API_KEY`.
|
|
754
|
+
- Store credentials in `.env` (which should be in `.gitignore`).
|
|
755
|
+
- For CI/CD, use secrets management rather than plaintext config.
|
|
756
|
+
|
|
757
|
+
---
|
|
758
|
+
|
|
759
|
+
## Quick Reference Card
|
|
760
|
+
|
|
761
|
+
```
|
|
762
|
+
memo setup init --repo <r> --org <o> --domain <d> # Initialize config
|
|
763
|
+
memo setup validate # Verify config
|
|
764
|
+
memo setup show [--json] # Display config
|
|
765
|
+
|
|
766
|
+
memo write --rationale "..." --tags "a,b,c" [--json] # Record decision
|
|
767
|
+
memo search "query" [--scope related] [--json] # Semantic search
|
|
768
|
+
memo list [--from DATE] [--to DATE] [--json] # Browse entries
|
|
769
|
+
memo tags list [--sort frequency] [--json] # Discover tags
|
|
770
|
+
memo inspect [--json] # Global facets
|
|
771
|
+
memo delete --id <uuid> [--json] # Delete entry
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
---
|
|
775
|
+
|
|
776
|
+
## Installation in Another Repository
|
|
777
|
+
|
|
778
|
+
1. **Copy** the `memo-cli-usage/` folder into `<your-repo>/.github/skills/`.
|
|
779
|
+
2. **Add** the skill to your agent/skill registry (e.g., `AGENTS.md`):
|
|
780
|
+
```markdown
|
|
781
|
+
| memo-cli-usage | `.github/skills/memo-cli-usage/` | Agent guidance for memo-cli operations | Any agent |
|
|
782
|
+
```
|
|
783
|
+
3. **Install** `memo-cli` as a dev dependency:
|
|
784
|
+
```bash
|
|
785
|
+
pnpm add -D memo-cli # or npm install -D memo-cli
|
|
786
|
+
```
|
|
787
|
+
4. **Configure** the repository:
|
|
788
|
+
```bash
|
|
789
|
+
npx memo setup init --repo <name> --org <org> --domain <domain>
|
|
790
|
+
```
|
|
791
|
+
5. **Set** environment variables (`.env` or CI secrets):
|
|
792
|
+
```
|
|
793
|
+
QDRANT_URL=http://localhost:6333
|
|
794
|
+
QDRANT_API_KEY=
|
|
795
|
+
EMBEDDINGS_PROVIDER=openai
|
|
796
|
+
EMBEDDINGS_API_KEY=sk-...
|
|
797
|
+
```
|
|
798
|
+
6. The skill is now active — any agent that loads it will know how to use `memo-cli`.
|