@vpxa/aikit 0.1.24 → 0.1.25
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/package.json
CHANGED
|
@@ -71,6 +71,31 @@ This project has specialized agents in \`.github/agents/\`. Use them instead of
|
|
|
71
71
|
| Documentation | **Documenter** | Comprehensive project docs |
|
|
72
72
|
|
|
73
73
|
Check \`.github/agents/\` for the full list of available agents.
|
|
74
|
+
|
|
75
|
+
## Persistent Memory
|
|
76
|
+
|
|
77
|
+
AI Kit provides cross-session persistent memory. **Use it actively** — decisions, patterns, and context that survive between conversations.
|
|
78
|
+
|
|
79
|
+
| Action | Tool | Example |
|
|
80
|
+
|--------|------|---------|
|
|
81
|
+
| Store | \`remember\` | \`remember({ title: "Auth uses JWT RS256", content: "...", category: "decisions" })\` |
|
|
82
|
+
| Search | \`search\` | \`search({ query: "authentication", origin: "curated" })\` |
|
|
83
|
+
| Browse | \`list\` | \`list()\` or \`list({ category: "decisions" })\` |
|
|
84
|
+
| Read | \`read\` | \`read({ id: "<entry-id>" })\` |
|
|
85
|
+
| Update | \`update\` | \`update({ id: "<entry-id>", content: "Updated info" })\` |
|
|
86
|
+
| Remove | \`forget\` | \`forget({ id: "<entry-id>" })\` |
|
|
87
|
+
|
|
88
|
+
**Categories:** \`conventions\`, \`decisions\`, \`patterns\`, \`context\`, \`session\`
|
|
89
|
+
|
|
90
|
+
**Session checkpoint** (do at end of every session):
|
|
91
|
+
\`\`\`
|
|
92
|
+
remember({ title: "Session checkpoint: <topic>", content: "Done: ... / Decisions: ... / Next: ... / Blockers: ...", category: "session" })
|
|
93
|
+
\`\`\`
|
|
94
|
+
|
|
95
|
+
**Session resume** (do at start of every session):
|
|
96
|
+
\`\`\`
|
|
97
|
+
search({ query: "SESSION CHECKPOINT", origin: "curated" })
|
|
98
|
+
\`\`\`
|
|
74
99
|
`}function t(e,t){return`# ${e} — Agent Instructions
|
|
75
100
|
|
|
76
101
|
## AI Kit MCP Server (\`${t}\`)
|
|
@@ -168,6 +193,31 @@ For long sessions or context approaching capacity, use the \`session-handoff\` s
|
|
|
168
193
|
|
|
169
194
|
---
|
|
170
195
|
|
|
196
|
+
## Persistent Memory (Long-Term Knowledge)
|
|
197
|
+
|
|
198
|
+
AI Kit provides cross-session persistent memory via curated knowledge. **Use it actively** to remember decisions, patterns, and context across conversations.
|
|
199
|
+
|
|
200
|
+
### Writing
|
|
201
|
+
| Tool | Purpose | Example |
|
|
202
|
+
|------|---------|---------|
|
|
203
|
+
| \`remember\` | Store new entry | \`remember({ title: "Auth uses JWT RS256", content: "All API auth uses RS256...", category: "decisions" })\` |
|
|
204
|
+
| \`update\` | Modify existing | \`update({ id: "<id>", content: "Updated info" })\` |
|
|
205
|
+
| \`produce_knowledge\` | Auto-generate from code | \`produce_knowledge({ path: "src/" })\` |
|
|
206
|
+
|
|
207
|
+
### Reading
|
|
208
|
+
| Tool | Purpose | Example |
|
|
209
|
+
|------|---------|---------|
|
|
210
|
+
| \`list\` | Browse entries | \`list()\` or \`list({ category: "decisions" })\` |
|
|
211
|
+
| \`read\` | Read by ID | \`read({ id: "<id>" })\` |
|
|
212
|
+
| \`search\` | Find by content | \`search({ query: "auth", origin: "curated" })\` |
|
|
213
|
+
| \`forget\` | Remove outdated | \`forget({ id: "<id>" })\` |
|
|
214
|
+
|
|
215
|
+
**Categories:** \`conventions\` · \`decisions\` · \`patterns\` · \`context\` · \`session\`
|
|
216
|
+
|
|
217
|
+
**Best practices:** Remember *why* not *what*. Search before remembering (avoid duplicates). Checkpoint at milestones. Clean up outdated entries.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
171
221
|
## Search Modes
|
|
172
222
|
|
|
173
223
|
| Mode | When | Example |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{FLOW_DIRS as e,MCP_SERVER_ENTRY as t,SERVER_NAME as n,SKILL_NAMES as r,VSCODE_SETTINGS as i}from"./constants.js";import{buildAgentsMd as a,buildCopilotInstructions as o}from"./templates.js";import{smartCopySubdir as s}from"./scaffold.js";import{existsSync as c,mkdirSync as l,readFileSync as u,rmSync as d,unlinkSync as f,writeFileSync as p}from"node:fs";import{dirname as m,resolve as h}from"node:path";import{fileURLToPath as g}from"node:url";import{getGlobalDataDir as _,saveRegistry as v}from"../../../../core/dist/index.js";import{homedir as y}from"node:os";function b(){let e=y(),t=process.platform,n=[],r=h(e,`.copilot`),i=h(r,`instructions`),a=h(e,`.claude`),o=h(e,`.cursor`),s=h(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??h(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else if(t===`darwin`){let t=h(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??h(e,`.config`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:h(e,`.claude`),mcpConfigPath:h(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.push({ide:`Copilot CLI`,configDir:r,mcpConfigPath:h(r,`mcp-config.json`),globalScaffoldRoot:null,instructionsRoot:null}),n.filter(e=>c(e.configDir))}function x(e,n,r=!1){let{mcpConfigPath:i,configDir:a}=e,o={...t},s={};if(c(i)){try{let e=u(i,`utf-8`);s=JSON.parse(e)}catch{let e=`${i}.bak`;p(e,u(i,`utf-8`),`utf-8`),console.log(` Backed up invalid ${i} to ${e}`),s={}}if((s.servers??s.mcpServers??{})[n]&&!r){console.log(` ${e.ide}: ${n} already configured (use --force to update)`);return}}let d=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(e.ide)?`servers`:`mcpServers`,f=s[d]??{};e.ide===`Copilot CLI`?f[n]={...o,tools:[`*`]}:f[n]=o,s[d]=f,l(a,{recursive:!0}),p(i,`${JSON.stringify(s,null,2)}\n`,`utf-8`),console.log(` ${e.ide}: configured ${n} in ${i}`)}const S=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function C(e,t=!1){if(!S.has(e.ide))return;let n=h(e.configDir,`settings.json`),r={};if(c(n))try{let e=u(n,`utf-8`);r=JSON.parse(e)}catch{console.log(` ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(i))if(typeof n==`object`&&n){let t=typeof r[e]==`object`&&r[e]!==null?r[e]:{},i={...t,...n};JSON.stringify(i)!==JSON.stringify(t)&&(r[e]=i,a=!0)}else (t||!(e in r))&&(r[e]=n,a=!0);a&&(p(n,`${JSON.stringify(r,null,2)}\n`,`utf-8`),console.log(` ${e.ide}: updated settings.json`))}function w(t,n,i,u,f=!1){let m=new Set;for(let e of n)e.globalScaffoldRoot&&m.add(e.globalScaffoldRoot);if(m.size===0){console.log(` No IDEs with global scaffold support detected.`);return}let g=h(t,`scaffold`,`general`);for(let n of m){s(g,n,`agents`,u,f),s(g,n,`prompts`,u,f);let i=0;for(let e of r)c(h(g,`skills`,e))&&(s(g,n,`skills/${e}`,u,f),i++);for(let r of e){let e=h(t,`scaffold`,`flows`,r);if(!c(h(e,`steps`)))continue;let i=h(n,`flows`,r);l(i,{recursive:!0});let a=h(i,`skills`);c(a)&&(d(a,{recursive:!0,force:!0}),console.log(` ${n}: migrated ${r} flow to steps/ layout`)),s(e,i,`steps`,u,f)}console.log(` ${n}: scaffold updated (${i} skills)`)}let _=new Set,v=o(`aikit`,i),
|
|
1
|
+
import{FLOW_DIRS as e,MCP_SERVER_ENTRY as t,SERVER_NAME as n,SKILL_NAMES as r,VSCODE_SETTINGS as i}from"./constants.js";import{buildAgentsMd as a,buildCopilotInstructions as o}from"./templates.js";import{smartCopySubdir as s}from"./scaffold.js";import{existsSync as c,mkdirSync as l,readFileSync as u,rmSync as d,unlinkSync as f,writeFileSync as p}from"node:fs";import{dirname as m,resolve as h}from"node:path";import{fileURLToPath as g}from"node:url";import{getGlobalDataDir as _,saveRegistry as v}from"../../../../core/dist/index.js";import{homedir as y}from"node:os";function b(){let e=y(),t=process.platform,n=[],r=h(e,`.copilot`),i=h(r,`instructions`),a=h(e,`.claude`),o=h(e,`.cursor`),s=h(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??h(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else if(t===`darwin`){let t=h(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??h(e,`.config`);n.push({ide:`VS Code`,configDir:h(t,`Code`,`User`),mcpConfigPath:h(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:h(t,`Code - Insiders`,`User`),mcpConfigPath:h(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:h(t,`VSCodium`,`User`),mcpConfigPath:h(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:h(t,`Cursor`,`User`),mcpConfigPath:h(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:h(t,`Cursor Nightly`,`User`),mcpConfigPath:h(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:h(t,`Windsurf`,`User`),mcpConfigPath:h(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:s,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:h(e,`.claude`),mcpConfigPath:h(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.push({ide:`Copilot CLI`,configDir:r,mcpConfigPath:h(r,`mcp-config.json`),globalScaffoldRoot:null,instructionsRoot:null}),n.filter(e=>c(e.configDir))}function x(e,n,r=!1){let{mcpConfigPath:i,configDir:a}=e,o={...t},s={};if(c(i)){try{let e=u(i,`utf-8`);s=JSON.parse(e)}catch{let e=`${i}.bak`;p(e,u(i,`utf-8`),`utf-8`),console.log(` Backed up invalid ${i} to ${e}`),s={}}if((s.servers??s.mcpServers??{})[n]&&!r){console.log(` ${e.ide}: ${n} already configured (use --force to update)`);return}}let d=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(e.ide)?`servers`:`mcpServers`,f=s[d]??{};e.ide===`Copilot CLI`?f[n]={...o,tools:[`*`]}:f[n]=o,s[d]=f,l(a,{recursive:!0}),p(i,`${JSON.stringify(s,null,2)}\n`,`utf-8`),console.log(` ${e.ide}: configured ${n} in ${i}`)}const S=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function C(e,t=!1){if(!S.has(e.ide))return;let n=h(e.configDir,`settings.json`),r={};if(c(n))try{let e=u(n,`utf-8`);r=JSON.parse(e)}catch{console.log(` ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(i))if(typeof n==`object`&&n){let t=typeof r[e]==`object`&&r[e]!==null?r[e]:{},i={...t,...n};JSON.stringify(i)!==JSON.stringify(t)&&(r[e]=i,a=!0)}else (t||!(e in r))&&(r[e]=n,a=!0);a&&(p(n,`${JSON.stringify(r,null,2)}\n`,`utf-8`),console.log(` ${e.ide}: updated settings.json`))}function w(t,n,i,u,f=!1){let m=new Set;for(let e of n)e.globalScaffoldRoot&&m.add(e.globalScaffoldRoot);if(m.size===0){console.log(` No IDEs with global scaffold support detected.`);return}let g=h(t,`scaffold`,`general`);for(let n of m){s(g,n,`agents`,u,f),s(g,n,`prompts`,u,f);let i=0;for(let e of r)c(h(g,`skills`,e))&&(s(g,n,`skills/${e}`,u,f),i++);for(let r of e){let e=h(t,`scaffold`,`flows`,r);if(!c(h(e,`steps`)))continue;let i=h(n,`flows`,r);l(i,{recursive:!0});let a=h(i,`skills`);c(a)&&(d(a,{recursive:!0,force:!0}),console.log(` ${n}: migrated ${r} flow to steps/ layout`)),s(e,i,`steps`,u,f)}console.log(` ${n}: scaffold updated (${i} skills)`)}let _=new Set,v=o(`aikit`,i),b=a(`aikit`,i);for(let e of n){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=h(t,`CLAUDE.md`);p(e,`${v}\n---\n\n${b}`,`utf-8`),_.add(e)}else if(e.ide===`VS Code`||e.ide===`VS Code Insiders`||e.ide===`VSCodium`){let n=e.instructionsRoot??t;l(n,{recursive:!0});let r=h(n,`copilot-instructions.md`);_.has(r)||(p(r,`---\napplyTo: "**"\n---\n\n${v}\n---\n\n${b}`,`utf-8`),_.add(r));let i=h(y(),`.github`),a=h(i,`copilot-instructions.md`);_.has(a)||(l(i,{recursive:!0}),p(a,`${v}\n---\n\n${b}`,`utf-8`),_.add(a))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=h(t,`rules`);l(e,{recursive:!0});let n=h(e,`aikit.mdc`);_.has(n)||(p(n,`${v}\n---\n\n${b}`,`utf-8`),_.add(n))}else if(e.ide===`Windsurf`){let e=h(t,`rules`);l(e,{recursive:!0});let n=h(e,`aikit.md`);_.has(n)||(p(n,`${v}\n---\n\n${b}`,`utf-8`),_.add(n))}}_.size>0&&console.log(` Instruction files: ${[..._].join(`, `)}`)}function T(e){let t=[];for(let n of e){if(!n.globalScaffoldRoot)continue;let e=n.globalScaffoldRoot;if(n.ide===`VS Code`||n.ide===`VS Code Insiders`||n.ide===`VSCodium`){let r=n.instructionsRoot??e;t.push(h(r,`kb.instructions.md`)),t.push(h(r,`aikit.instructions.md`))}else n.ide===`Cursor`||n.ide===`Cursor Nightly`?t.push(h(e,`rules`,`kb.mdc`)):n.ide===`Windsurf`&&t.push(h(e,`rules`,`kb.md`))}for(let e of t)c(e)&&(f(e),console.log(` Removed legacy file: ${e}`))}async function E(e){let t=n,r=h(m(g(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(u(r,`utf-8`)).version;console.log(`Initializing @vpxa/aikit v${i}...\n`);let a=_();l(a,{recursive:!0}),console.log(` Global data store: ${a}`),v({version:1,workspaces:{}}),console.log(` Created registry.json`);let o=b();if(o.length===0)console.log(`
|
|
2
2
|
No supported IDEs detected. You can manually add the MCP server config.`);else{console.log(`\n Detected ${o.length} IDE(s):`);for(let n of o)x(n,t,e.force),C(n,e.force)}let s=h(m(g(import.meta.url)),`..`,`..`,`..`,`..`,`..`);console.log(`
|
|
3
3
|
Installing scaffold files:`),w(s,o,t,i,e.force),T(o),console.log(`
|
|
4
4
|
User-level AI Kit installation complete!`),console.log(`
|
|
@@ -414,6 +414,73 @@ git_context({ diff: true })
|
|
|
414
414
|
→ check({}) → test_run({})
|
|
415
415
|
```
|
|
416
416
|
|
|
417
|
+
---
|
|
418
|
+
|
|
419
|
+
## Persistent Memory (Long-Term Knowledge)
|
|
420
|
+
|
|
421
|
+
AI Kit provides cross-session persistent memory via a curated knowledge store. Use it to remember decisions, patterns, conventions, and context that should survive beyond the current conversation.
|
|
422
|
+
|
|
423
|
+
### Writing to Memory
|
|
424
|
+
|
|
425
|
+
| Tool | Purpose | Example |
|
|
426
|
+
|------|---------|---------|
|
|
427
|
+
| `remember` | Store a new knowledge entry | `remember({ title: "Auth uses JWT RS256", content: "All API auth uses RS256 JWT tokens issued by /auth/token. Refresh via httpOnly cookie.", category: "decisions" })` |
|
|
428
|
+
| `update` | Modify an existing entry | `update({ id: "<entry-id>", content: "Updated: now also supports Ed25519" })` |
|
|
429
|
+
| `produce_knowledge` | Auto-generate analysis entries from code | `produce_knowledge({ path: "src/" })` |
|
|
430
|
+
|
|
431
|
+
**Categories** — use these to organize entries:
|
|
432
|
+
- `conventions` — coding standards, naming rules, file organization
|
|
433
|
+
- `decisions` — architecture decisions, technology choices, trade-offs made
|
|
434
|
+
- `patterns` — recurring code patterns, design patterns in use
|
|
435
|
+
- `context` — project context, domain knowledge, business rules
|
|
436
|
+
- `session` — session checkpoints for resuming work
|
|
437
|
+
|
|
438
|
+
### Reading from Memory
|
|
439
|
+
|
|
440
|
+
| Tool | Purpose | Example |
|
|
441
|
+
|------|---------|---------|
|
|
442
|
+
| `list` | Browse all stored entries | `list()` or `list({ category: "decisions" })` |
|
|
443
|
+
| `read` | Read a specific entry by ID | `read({ id: "<entry-id>" })` |
|
|
444
|
+
| `search` | Find entries by content/query | `search({ query: "authentication", origin: "curated" })` |
|
|
445
|
+
| `forget` | Remove an outdated entry | `forget({ id: "<entry-id>" })` |
|
|
446
|
+
|
|
447
|
+
### When to Remember
|
|
448
|
+
|
|
449
|
+
| Situation | What to store | Category |
|
|
450
|
+
|-----------|--------------|----------|
|
|
451
|
+
| Architecture decision made | Decision + rationale + alternatives considered | `decisions` |
|
|
452
|
+
| Pattern discovered in codebase | Pattern description + example locations | `patterns` |
|
|
453
|
+
| Convention established | Rule + enforcement approach | `conventions` |
|
|
454
|
+
| Session ending | Checkpoint: what was done, what's next, blockers | `session` |
|
|
455
|
+
| Bug root cause found | Root cause + fix approach + prevention strategy | `context` |
|
|
456
|
+
| External API behavior learned | Behavior quirks, rate limits, gotchas | `context` |
|
|
457
|
+
|
|
458
|
+
### Session Checkpoint Pattern
|
|
459
|
+
|
|
460
|
+
At the END of every meaningful work session:
|
|
461
|
+
```
|
|
462
|
+
remember({
|
|
463
|
+
title: "Session checkpoint: <topic>",
|
|
464
|
+
content: "## Done\n- <completed items>\n\n## Decisions\n- <key decisions made>\n\n## Next\n- <pending work>\n\n## Blockers\n- <issues encountered>",
|
|
465
|
+
category: "session"
|
|
466
|
+
})
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
At the START of the next session:
|
|
470
|
+
```
|
|
471
|
+
search({ query: "SESSION CHECKPOINT", origin: "curated" }) # Find last checkpoint
|
|
472
|
+
list({ category: "session" }) # Browse all checkpoints
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
### Memory Best Practices
|
|
476
|
+
|
|
477
|
+
1. **Remember decisions, not code** — store *why*, not *what*. Code changes; rationale persists.
|
|
478
|
+
2. **Search before remembering** — avoid duplicates: `search({ query: "..." })` first.
|
|
479
|
+
3. **Use categories** — structured categories enable filtered `list()` queries.
|
|
480
|
+
4. **Checkpoint regularly** — don't wait for session end. Checkpoint at milestones.
|
|
481
|
+
5. **Clean up** — `forget()` outdated entries. Memory is only valuable when accurate.
|
|
482
|
+
6. **Cross-reference** — mention related entry titles in content for discoverability.
|
|
483
|
+
|
|
417
484
|
## CLI Quick Reference
|
|
418
485
|
|
|
419
486
|
```bash
|