From 0e913a25ffe25780dbc68b0d7aa6c21943d1a22e Mon Sep 17 00:00:00 2001 From: Alex Newman Date: Sun, 28 Dec 2025 23:32:52 -0500 Subject: [PATCH] Refactor mem-search operations: remove outdated documentation files, enhance search parameters, and improve token efficiency guidelines. Update MCP server descriptions for clarity on search and timeline functionalities. Remove unnecessary zip build process for mem-search skill. --- plugin/scripts/mcp-server.cjs | 2 +- plugin/skills/mem-search.zip | Bin 33246 -> 0 bytes plugin/skills/mem-search/SKILL.md | 356 ---------------- plugin/skills/mem-search/operations/.gitkeep | 0 .../mem-search/operations/by-concept.md | 124 ------ .../skills/mem-search/operations/by-file.md | 127 ------ .../skills/mem-search/operations/by-type.md | 123 ------ .../mem-search/operations/common-workflows.md | 251 ----------- .../mem-search/operations/formatting.md | 403 ------------------ plugin/skills/mem-search/operations/help.md | 171 -------- .../mem-search/operations/observations.md | 124 ------ .../skills/mem-search/operations/prompts.md | 125 ------ .../mem-search/operations/recent-context.md | 134 ------ .../skills/mem-search/operations/sessions.md | 124 ------ .../operations/timeline-by-query.md | 194 --------- .../skills/mem-search/operations/timeline.md | 171 -------- plugin/skills/mem-search/principles/.gitkeep | 0 .../mem-search/principles/anti-patterns.md | 176 -------- .../principles/progressive-disclosure.md | 120 ------ scripts/build-hooks.js | 17 - src/servers/mcp-server.ts | 6 +- 21 files changed, 4 insertions(+), 2744 deletions(-) delete mode 100644 plugin/skills/mem-search.zip delete mode 100644 plugin/skills/mem-search/SKILL.md delete mode 100644 plugin/skills/mem-search/operations/.gitkeep delete mode 100644 plugin/skills/mem-search/operations/by-concept.md delete mode 100644 plugin/skills/mem-search/operations/by-file.md delete mode 100644 plugin/skills/mem-search/operations/by-type.md delete mode 100644 plugin/skills/mem-search/operations/common-workflows.md delete mode 100644 plugin/skills/mem-search/operations/formatting.md delete mode 100644 plugin/skills/mem-search/operations/help.md delete mode 100644 plugin/skills/mem-search/operations/observations.md delete mode 100644 plugin/skills/mem-search/operations/prompts.md delete mode 100644 plugin/skills/mem-search/operations/recent-context.md delete mode 100644 plugin/skills/mem-search/operations/sessions.md delete mode 100644 plugin/skills/mem-search/operations/timeline-by-query.md delete mode 100644 plugin/skills/mem-search/operations/timeline.md delete mode 100644 plugin/skills/mem-search/principles/.gitkeep delete mode 100644 plugin/skills/mem-search/principles/anti-patterns.md delete mode 100644 plugin/skills/mem-search/principles/progressive-disclosure.md diff --git a/plugin/scripts/mcp-server.cjs b/plugin/scripts/mcp-server.cjs index d25d23ee..8c7adde8 100755 --- a/plugin/scripts/mcp-server.cjs +++ b/plugin/scripts/mcp-server.cjs @@ -29,7 +29,7 @@ NEVER fetch full details without filtering first. 10x token savings.`,inputSchem \`get_observations(ids=[...])\` # ALWAYS batch for 2+ items Returns: Complete details (~500-1000 tokens/result) -**Why:** 10x token savings. Never fetch full details without filtering first.`}]})},{name:"search",description:"Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.search;return await fi(e,a)}},{name:"timeline",description:"Step 2: Get context around results. Params: anchor (observation ID), depth_before, depth_after, project",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.timeline;return await fi(e,a)}},{name:"get_observations",description:"Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs), project",inputSchema:{type:"object",properties:{ids:{type:"array",items:{type:"number"},description:"Array of observation IDs to fetch (required)"}},required:["ids"],additionalProperties:!0},handler:async a=>await Od("/api/observations/batch",a)}],cs=new oa({name:"mcp-search-server",version:"1.0.0"},{capabilities:{tools:{}}});cs.setRequestHandler(Ca,async()=>({tools:hi.map(a=>({name:a.name,description:a.description,inputSchema:a.inputSchema}))}));cs.setRequestHandler($a,async a=>{let e=hi.find(t=>t.name===a.params.name);if(!e)throw new Error(`Unknown tool: ${a.params.name}`);try{return await e.handler(a.params.arguments||{})}catch(t){return{content:[{type:"text",text:`Tool execution failed: ${t.message}`}],isError:!0}}});async function pi(){_e.info("SYSTEM","MCP server shutting down"),process.exit(0)}process.on("SIGTERM",pi);process.on("SIGINT",pi);async function Ad(){let a=new la;await cs.connect(a),_e.info("SYSTEM","Claude-mem search server started"),setTimeout(async()=>{await Id()?_e.info("SYSTEM","Worker available",void 0,{workerUrl:Pt}):(_e.warn("SYSTEM","Worker not available",void 0,{workerUrl:Pt}),_e.warn("SYSTEM","Tools will fail until Worker is started"),_e.warn("SYSTEM","Start Worker with: npm run worker:restart"))},0)}Ad().catch(a=>{_e.error("SYSTEM","Fatal error",void 0,a),process.exit(1)}); +**Why:** 10x token savings. Never fetch full details without filtering first.`}]})},{name:"search",description:"Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.search;return await fi(e,a)}},{name:"timeline",description:"Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project",inputSchema:{type:"object",properties:{},additionalProperties:!0},handler:async a=>{let e=di.timeline;return await fi(e,a)}},{name:"get_observations",description:"Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project",inputSchema:{type:"object",properties:{ids:{type:"array",items:{type:"number"},description:"Array of observation IDs to fetch (required)"}},required:["ids"],additionalProperties:!0},handler:async a=>await Od("/api/observations/batch",a)}],cs=new oa({name:"mcp-search-server",version:"1.0.0"},{capabilities:{tools:{}}});cs.setRequestHandler(Ca,async()=>({tools:hi.map(a=>({name:a.name,description:a.description,inputSchema:a.inputSchema}))}));cs.setRequestHandler($a,async a=>{let e=hi.find(t=>t.name===a.params.name);if(!e)throw new Error(`Unknown tool: ${a.params.name}`);try{return await e.handler(a.params.arguments||{})}catch(t){return{content:[{type:"text",text:`Tool execution failed: ${t.message}`}],isError:!0}}});async function pi(){_e.info("SYSTEM","MCP server shutting down"),process.exit(0)}process.on("SIGTERM",pi);process.on("SIGINT",pi);async function Ad(){let a=new la;await cs.connect(a),_e.info("SYSTEM","Claude-mem search server started"),setTimeout(async()=>{await Id()?_e.info("SYSTEM","Worker available",void 0,{workerUrl:Pt}):(_e.warn("SYSTEM","Worker not available",void 0,{workerUrl:Pt}),_e.warn("SYSTEM","Tools will fail until Worker is started"),_e.warn("SYSTEM","Start Worker with: npm run worker:restart"))},0)}Ad().catch(a=>{_e.error("SYSTEM","Fatal error",void 0,a),process.exit(1)}); /*! Bundled license information: uri-js/dist/es5/uri.all.js: diff --git a/plugin/skills/mem-search.zip b/plugin/skills/mem-search.zip deleted file mode 100644 index 455c2d47c4e88e3ec6977cde06ac8dc352e6ddcc..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 33246 zcmagFQ;;a#wr*RtZO*c7+qP}nwr$(CX4y7p*|zJo|8r&Cde1OVpxP_W?ryIkC%0RTas z0096%Q2yR7|9^^vMyLEs5ww3TVrOsSXy9yNXY2Go>uI@)TWJ4X|Cf6I)P(@h@(9pU zRRmNqfCK<2!vX-H__y_p>}+i8Y-!x=9IZ^P?cAJbZH)ixk!7A~EM7nVe~;XwzHPfX zhT40g1Y`ZX9z~%~H4(}lcG#lPg3XHUnFth3L?(gQ!ZLEuF*LD-9<7JmQv)Sxhi-1C z^;9O0Ty9S6)Xg*$g<{gRQ6>vI6wPdg!)fLvCvV-X%&{RJ(u=O?!h%|D;(?Y~?rVHQ z?KN-O5z%3|l+nmDCz3u~qt<fN4VbT4a-WW4bD3ZF2nhI9?E{S6M)4 zDyW&qgueTTP_B7vU^5Sr*h&)l>_v-4(_7|+p#(Ydv>kIZjw~VCN)z+k!^l`yXJ;me z<#mV$8k1f_Pshqx`Ci1rIc`Xs=}c;dY^=d=_(>G$YB$`e<8Q2 zQ+T9Aadv8D6Tu-$s`wn9iO-sKZ(bcBd4aS%q`)&h`Wo&7kcah1KySp51P*UbOG(b2Ke+73F`8lNWaE&1s0>exC9n}!@ajCoyh~n9td^dtJrQs)sKe$Kbl3Nuq z6&s{iR2jhfgEG#dxi2^P-}iLZ+c!_(LO6j$HxOzjz;UJkoDioBBfb;81ho1(xIecB z<1m3~I$9FImxDJy6ZWck2s2ExAIHpSdo6d`%NfaNF#>(Q!3rlC*(M-2B#AZh2GlCK zcL~s?fQnVL8ieVDB+c$IUupJ@dLvUue&!lu(M-IDmxI>DsGHWG^W47-$R63nA~^m^O1U*H#?J!GzZyrb#tqiC0X)b~OkE$C`s9XVh^#kJhhE zHyk)+ta^1$OtPw@T%>8mDbp*wmA~+uyCTB}Rkm!p2Xe*V%G+A1SodUp_91Dhd&Rbv zl{VzJliQ+23W(1_sZI5}>r9Am`q0pCJ|GuFf<0}W;f%w7+4DOKGHe`Y{P!2GG|Mb& zhe4K-OFj2e6&eCYLt2TK_2TU~XPhfM-9TDT}M3&y<>9<@g^F+PmgWf}(yZpmGknR|DWjK_hkD*0;1 zl=gW0%d|Cud}9chf{?T!+OrfhI^xezqo!gR!g0H9+ll|LMZ5chQ)TRDNmsFSPeI%| zeB=4{(sb?HK+()L=A8Id7_;kLv@tJtgyvfwn%%`48-P!luI(L+GoI!<9c$t;2EM^=Q92)^>b2)30c;j1fBy7U%ALF z;qm@J=6cX+hAgVNyK>$Sn`x-I39?U!z>joGpMws!(DS?>#79AV>bQD*SEY zCSVM1@j(z*lOb@7FuLhxpSrU*&%B*EEv}1e%F-F|ZjDE~8tr#K4g<4XR)ruopq;_O z`tRz|(dN`|h67CsHOnFiUcWSyH&z{27aIj?x8VvZ&%9o^|13C*j@Rg&dFJt~JoSn& zgMy%pG1ox2cCmL2sQtpLtX($m;y`&DElnq@7S;&c@de|<<4P~81zC?yivIEZ?2)or zH5!zuJ6lGUG-4}jBPVoU z1KC5z9igex^|Be->M0)h=Eb}A1hs3nnLA%;RXMiIT)h;I$pP+KoU-q7TNwoltl0Jl z4y&TW|9<@{_1|s`VE8-}m2H`SO}U~GA3%uXnhsu%%lV!+?dyuGL7vjQLy5D*0~moS zUx^d4cb7rOJ>8#SN(ctAQrSX5_;s~y^%VKrIr+dHwfc-Pr>V-4x4V(P*&`k*uOip{ zxtFD;ig|p7ZeW43+gcal5Wy#krtj7UW?#rRffe2|^RiiOp(LeU(PuO(Nh@<=SuF_mTo z=lj8CdK2h>kt`=tR|} z?Mgp_U{9nA@5SS~D)zJjg*0Q)SST$^P;@?ILTLe+YFd)L#A#9uPK`J-xv8S_d`=lk z4Qri{xQxhQ!hXTk@DFZ(J7z7kB=lV`|*O)3l&;(l0bvXAN<9 z_GF;J9r`(WB{Ba*);qj>VH+WmnMYb(Ye}AVSkQBUu35L-TU2Sy3_4y$WuK?HxU6}_ zbZ@$+EKMq*Oo16Mj%;A2sF)ekg=X04BvPR-?@ZX($!7cXo$U2Vq~Lv}Xg$xmllm6U zZwAPEHQ$zE3v)L`ZI!V_`TCOCbWe8^*?irN^v|0|-A@ z8Bev4Z+sB&%VirEHj|-)U{tA?QDr%!_);W3NjT+<_geUZ21hs%yX~FK4es*o?x5jr2KkzC#`5$aSrd9wTLGwunxI`LUjkRr=z9bcY}LQb9{rG8((8Ml{fGc&9R4D z;Xn#vHYTr3O#8SdX`io7#CrSBp`%sko*<|c&S$GSN!>r`-T1x(pV<$Q7xjE&dt1Mi zJv!KfZj5@0v~ii^ld+wCz4R@hh4LJ+72wcbSc7&*soSw8OEl;gXtxr)><0!o4u3aI zZsAY>n&_fwg|xY%fZ5h5kud&_`81240T%B?>!AU}=<|Bf;(;4Df|vP#|KMv2+Q$F< zmRh`O@cVg)QyGKLq;!tZzNz}Ez@tk}-y4z_*&4r0O#~XSk=AdN> zfxN(0Uo7}!#`)4q>Qn-BFgJt;-%Rkag^9i$?En-{E8$8P zn&aZ?Cx3>gP#czqhU2CGS_x%6#`9^Ok#s?m6W{Jsd6>HM0x=)IP=T5qX|pXU3RTVd zf=Q@!6m#d!0U?t>B50~9$cHxr;~wWe6z079jl&8;t^=V<*xoMfCqkE9*?_4r>CYg3K;iq^_kuD;vH%^AY$?%cPt9 zBs~c7Ov5r+1=XvSR{gHMmeM4WI&1a>`e;RCXCsj`R@CYyYyHeZ1Jji$*+CG_=c%)o`ref4kGvU z`MO;{O>6sAwri5M78nsCgOy6N)r8~Ddvny6%<$x~cvHTQ--w^^{>OUV7TK!3 z@zbn|Cd$&D;b!~I26-*JZO$O?rv6yI$gxQHW$*Ce9Y8bX-i@+Zx#Yu-S+lbBQGm9) z#ZQBcfxv!VJS)&nj0|_ZYc?b0cGaS@srrM)A?{Tb5-+4`^vy00_#Lp_8+-pjzC~Q& zzy(jXFH(*VM$=E_T=F9f-WOX$ML5Q7JuI0n@lj$ZMcO0N1BU4YX6G@Z2mW_sbmoHZduphyIz^xW%QK5XX zeGGhgvFHj%{%wO8c|qch)AAsTxP=4qUqdc(p%zu3T4U}7wusFLV}LJTO~{o?SJAy3 zTwJkmQ2^1Rk0fcQQjynx2KLE$(@gqg%aoK&fuGpXu$NZ*aKWPP-dU z8SzHfzivZm5j~hExpLL5$rKBDQv;1&Nlr%a+cnOSVAeav{9tY(Ku;ZR$66@e=nn7B zmmFjLe{txlX(y#WG7I7M6{zqH{3L)$RMCD3H<7u7Uj;xtO;^K@vJbHQ64MXYbv?0$dva2%N-CrfhzEO4Lu{?UCj3jBA(EZqV0xDiclu0gwCu$rRe zpA}c&C+Vy4){$N1bAVlA{Y+^G@(+w}C_{ss(tfCb&W$W^39g5hKd>%Jp54dZLY@+A zcd%Cr$jodqBz`V#OsA(>Z1@q9=wPqQB7w2w$s>&lb3&O%Qsv#%T1wG|*x2SPQV1=c z6iS%Z6fuz&2r@#aw#j&)dOBw#Ay5t#^bt2|X#HdP_^pa95?NNSnsq?7zpjq@YrDA4 z@?`_5lNkrQ#i zgbW($V~GmFpe4n*71{m~lyK59wzJ2K>AVaAS&(bX^*xa=CESk^)x;mZa=sX`Wl(jKQ*F_DD+aA^fj6~_CvQb*zuhX z4d8v4oy6{h;vPtvkT8&+3^s{%t{)d3bo>5Zf!R{C(;z&^tSsY2Iw#Um{sdKK;#`8r zVVC7;X7oV4+seqP>Q?iRT05DNZXynoweGsi&F&0Ym2T=^cW|H#UQ!Kq>99 zd|NO?7=92UdK!^WwW))HluPRc#aWC8SS53vuM2g;Nf_@?B#tGss49;6(LjNlo@i=~ z_7Xu4Axs)d9vXw2lHPfP}4@8QJv=Iywk?DJ4eHC(Jr345k(JA=hS0W z>(uTZJ(1m!@dOY7x8xj1C#E!FY1R!bN7wR{6Gh9WvBs2*-)qs2TN=uf81od9A1}dL zbu$ITPHEdXN$uCdw6*2*{g$3oa|>z0u_%H|rL`>}HkFF?65~(3DVJHj>6tkDD$MqQ z-})_4eWC$4Q?hUetg&-s^Xj_iaa#laSOPlVrtSdpzT0&sP~^nKjeNc56ZzcGahf?V zTU=*5W8U9Qc8}4MEspKx(as1Y$0Dta51BEqwYa3)y}^8|7CyQ1%G?~POSBQ#nSose z7J7sjTMf!K5V}aaDYcbFW7aN7ZKWigbx5}wGNOng&f$c>ZThcP&I;$wu5^8{89Jm|ve>)>M^$&-0a0lTNtm8$oGZVCjxl}JI|7Iq z*YH%3USD+vzbZVT$UdKG-uy9|nXp=~-aA!fx*kpv$d!6a9KF(N(F{hPhpf9Y7@ zOHLBLFHEIdn{DB7)8xb|(fwgH^bx9i!|wfIM6`?PI~kGB*Hx}(U?ub9$~Ns(<^|1K zpU1;t9z1w&>Eoi<39+mmMMKOx)he2mdZC)?NiFvRX4jK{b>z@v-{7t^DcEt~v?fL; z2Gy|GNRd<_F%#xWhHAHGP1YtDyN2B@F;vF{KNx)hN}`HqiW32-LIX~#9DA$j%u=Te zT?p0BnG9TT^Fu((kat%R?!i`u`K6|mLPL_F9rs}C{F~Iisti*09e9>~2j8O=rGbCZ znlCJ<^JED)Ckb+TstjnJ&5KYA5f|27Z6EgcfO3+EjJKUll%fK-P`RlkGv4hrSZqw&wK{6f)Llf}Plp}Ktl5&(uS#QF%XT=CCa2%{A76LoDEPN-%iFuX$`Y!j z#x|R+wu5}O4_-5`<$RW}*ql(hQT9{6?gn)Rm}+nO_0=&JC@N6ZJ(rvYt)-%sERv+P zGQ)fC`x5HCoF;o)23|b9u^M@584dx$=(l@7+t4i#lyo|upQYQ#x(UNzq}(TC2P1V} zAOs@%l5J&@(F5Ci6QN{h6ErIgtnw^eW*J`fTHjJudM(}_sp$781R0?+5b~!iEX3!I z=}>Fzh^|(i9VhIYKn=Vb*t(mq6BBY<3M?4B(3>Y#x>S=~{nlQWS86Im&y6d;1?2fs zTXP%h*7e-CNJG=0e)ybP-3c72Id^581s0G0VPO85vqCE*mwz)U{%lF2g*4gfHZ3IIU)Z^7hjVPj%#VQWJ3H~w>QF>&p! zF=Z^OU@ab1&Frw3G)ommTkLT@tRzOx;dq-#m=KRwS@$6tAG?9J(8=RnJ;TVNUI%!Y zf6t!CCXIpTOdAP$DLUQtw>4!X{(Ou{QCK?ofr0$c7hCGgfE0r^upqtHHjNj7-sy>N zo;wy8`Aw|AUd_RBm+oiILSJj@DR8D~W8e&!G&0O1v&?0Y^`TZfuM`=AY-A9`yyH$t zh}D9ZlGUJC4M3fGXq;(9oG6*ecKi7t)w#kMK{U44;|w0QqZ-?ROJ~=2g0c0M z1IHz%;Oypxjyq=oXiyP*6z&lg?AK>l5T#h!hBoTCjyCzg;kb#I?cHF2Oql4qzwYD_l$yq`~wTncB%wbS~ zU!1QgHLO{vc%%!*wIg$RAY}kjNEl-R=hB5&y;;J_q=bp-mTxK#o24jav)*@uztGyQ zIu7%#KHRr_mtQT>)&;a*ho}&Dz2@b%6nmun+cJE=y(CZ}$yj1|r{KYyMd?QLQM7Zw z_{PnSzuY5(rFJxl#gCY5V<>e%(xp_?y1%LT z^R!TWl%Icwg<3lZR;u~{HPw=SUg%iV4;-HUG(%FIW~tpVfiXUKgVPK=qWGZV!08fa zv|{?WxMIrimL!rj2x4L7Kt&Z1g~$Aew29FqulQMwZS~RbIPb)(?L%|}XILY)Q%CoG zhG@qR)Js!W5!%E$je6(z{_6`tyxLl*mL2d4CWsZ~$Vt%wI$79Wm)7z3k}_1iLTjbT z5mMhb=QJ|pC`a-*=RcuB~&3Uy-1Fl32$YzZBSUV3TWn>sl74S@1lzO z*n@0nHltHhvLW6-LYTjg9Sch>1sNBIeay=Y87by&&l|b#&O?&l!tlB&i{nl@5}ZiT zKjyB0DbIMPJR?=G*LXWQ;kN{fYJhOqTc;bvJf5>MMzpC$s+h_gE;pZpraZN0jQk?e zCK|%Z?C+^REv-)2Iy4(ywBC~XQ}4|Qdi|`=d_z5mZOw5&lDyNX9)ckuqGXTRVQ)P5 zhbQtz5L7kjWgZRFzVp0s9#6RM7{-6EYsqt(>ElVHi;$$LSzCq~e&4@Pem{P>RJ3pb zW`S}Z?on!th(@i!r&p*OjvVOZcTIc=XN+-}>16<^FamKH1B6iao}17QylGT3`f=z|7hhYwqcwI0xZFh3qoJ4;xJ z9t`@-wyTIb8leqA47^hJ^NyVp`s`DI$ZCln7aF}7!7bj_Rl?-9R+a)cSLVxVZvJM- zj8Wb4`SvHhqT0lqS)U)sE{$uPwtus^aAQ3dQ=dxEtk(*rqFS&wnbiuT@=PI5Qb_8+ zSBpPhKX2jNg)}l&V~6h>`7j5Dz^?9G9{FQ@v}BFPN(e>g!d}ASu}&zj>Z$krT}9rr zrODOgq1S9yEx|Bupo91A8roTv*8sk!+-|k+Y4O#@>%fX^>!+6<%v`S!W_Ooo^hsNz zS1r+w!@TRryl*~HGcnEqw8~X2$@hw%-#lak)Xocgs2YpBB{MwNYZmBt6R(a?kh)CSg8g_y%cevhYRE*Q*6ft+OV&F(a3lSK z<%<4xax+&MuOey;@N$MbU~L8mi6!}j)tG3dFx|WJQLsY*VK2P?j9={IbD2osNC1Iy z)4T+}i)9TZyM|!c75PS^s@|lAMPqd6?JP_Q)=%Y|RRF2Nb`Rfvws`Zpd+gl$IY}U} z=ath*6vZKBhD>U~$5QPQUoSfj3|J5Hw-zbsebt+NzgyoG*G-&IHur{0BUHysB1vA) zKKJQM-ifFQ^0f^b{!`ChAX{3G`np76hs+zyx|30R=a%`y?~3VJ+TF&+f&=Bumyt0Ju&#+E2F`WQP^}nd zoSl0Q`laZrb|!1_YO$RWSvuV-Uo0wc&R;flk@UWqlhH{kU=yBJfhO4U6YlfC2rYs+vi<4Xbbw`Fif0stWVk1fN0>=dSL zH$@S8A1J`?3lc5Ilc_rz{0YP#7TIl(*i`pg1qf=!Q`#AZP2AKHL)d+S3&}la3s%v3 z9wXjCe1c~#6N#RTv_wF)NZrg%{CYE<@VxtBxf3Jy)WF^i2aFQzXNy$81d5G`j5yE$ zqxy}z2*e2JnAMm}gQXvN&1+k{3?(2c5|ft9^(AHRQUYW>2t%ZiG#Lsgrv;l>rXre_vSW5l}#iNBwYHIc`q-M-bk_7 zRc_ioz56MnZ(6i8lxI3~Y>$2zEk3SfiH6cy>1;jJNVz!0V2T_LpsOM74a(x@f$3xJ^5SZ)>Pm-&7J!v zI1RbT(rn$B2JSsafrX@VBhzQJsR^`#L2{r}G7{O;wVP^vr(Gh4$M>enE%ZyFsIFK> z`yxUu0z)DodwLdh1bY`5?{a<+$P#@`fhK27nfF_ubKJI_Q_(aC2M!R?Tz!4w{uCwU{DP?%8bK5jpc( zISN7Yte+B%rl(oljV z#vo8WhF(KelVUZHEcnC>>!4SFBTm2&WB4xgR+~gFr4{0k6BpgNdN@`ATi}VLvuFg* z;|i{7{luw6P(6Qgty>IPL=RtseLXoC{lgmj!P8!}fRk0LSO0eOVqzs4<2L46w*SZP z69ztKxYk5DfyP4Zq1y84J=6vyuMK>m!Pi{DWBXOe8Zl&r@2lgI*(;rq9R{}^Ip?wQR8@t7cHKYX4TWC=h~ElEsf?7g%(*-8^9!!mC2Z&M}uM`r^GkMJ{)9t9*Gx9BDV}6O|8`!24PuKR$mr8p@IC_YOm!h%Jd#+(9p!F!!P4;_BR)$3I$DBU zl(?2!QiE_hGDeWmr~yJMXw`L?^|TR(c2jPzsC?mi|c0fYVzqX^u%~-M#K|$~rld?v1PFv;r5?D5x!mqGcUh0D6XYTmvyQDgj+s2j(kip0NQ}{p>4lMY_id*P`;nz^ z5+OyTz+k|pex_or$}yXEeJ>~`h*F4!Iq_zHatrvz_e4Z$pW|V)e9bzyc#1es zKuOh|LM*DmP&AuhL6Ev7jy(0wmAJZAUumlC_)}-k`jJm^_DQx8U4)f>i?FbpkT8N~ zMCizb*v-afOUazLqoVN=EMSqV;Z4a&a2)oyLeE)YuFis$Im*rhQ5bHV$$dn?nQKN@QJe_pc}Ni_}o;j7a`2V%npKCCC_hzq9vjp-ig- z6BR7p&boWDeu-g5DXtK7d$#e&$C8Mkti7w)#}APRogL99Skx5_)?=>#j%x6N%h zc%X(Di_E`huqmSu2?s?OV3LD29=}2V6|R9o2owT;gJPn;K{4^ah3j7p{~Hn;nb`lI zkoez-c#hiU-;fyNZ%B*)CqEQ=mEE<>uZCjL2xcDDJiZcDXl@?Ss-aXUs^}WsIf!TY z0{jf;Rlw7aXYfZ(GV-u}m{V^J=?%Z{=M>kKq&>pSy4$dfGfL#T@KoCra?yxtDv+y! zX%Z(-R%9S`VLE+Ugqn=e)FHoZkbGm^z|M@wNVX}jI=m3@3uEMJD^~sFDw-=*9Qz`K zUQwM}C{>>#FN!S3W{AU0HodwuIbtk3ySi0Lt|iK>n-oo>Itu19_dR6ADMMymIIC5z zA2Y#GJa$~@;){KmA~un{v!eski7RSoO*+L?XW*!0Nx*qUHA29GKMu38n;Ku|kvk2=09 zBR*7Rm1Gqu9^T(AG@2k*>1Pbdz=-$(Y)_gFd;vCfV~Pebcl$WfjO5*OKv6)kScb|; za4zDJXh@6bq*57znQ%#06R3ott;Ea(4x~~aSK*7C(V*RMZ^+YJh`^JlI1XMk>}mr@ zfUSyFDAAcTM3FtpC6h`RB$tCWLKBmL0zPC^iZ&osJgsHYnJk3 z*oTkt$5lA)<&7H;cKr{z;jB9?Dt9pyHM~ZsvVPY_(71}ecssIMEOwiioSDXgX^D`j z_b;qy?2z#p_JyOZzyIj;;Nh|?ChCgz;63)x8grW^b3#+3@@m)Y2aGTZ2}pkhN?z_~ zJej0IBn(n!&;+|Uo@WUY7hL( zY%Ipe3%FE6*(r_01OP(Mn<3+IMd4R~_*Pzvz=HN-U%1}_Nz8V;%d-@3d)%^VkiMd5#b3rhFo_PH@2+N5*6ZfeVKVN~o zj-Oh-|A?!L`El6iK!}`;i-ULbQia?$G3-OKC&_tqvs3832irko)DK13KA9HAJ2$qf zt{$~C^Qv52zRm^Mim}R=n{r=~9l(4KP;5PQ@V4}u(D^FAxcZ5UumN%G;t<#kU%2)F zljHVwz9=bd^v}&=87VbYSn_ZrdIUx>kr55p>l7b(M~;5z$6F^23UNs-pv7uxfRB;>j&$I^qXV&5r08yJtXFfI_(n(*}m1 zD?b*VNA2*OBCWPRghRbfGSKGAj78rDA^JDh*P#~ozHLt%uwL_vpqxk<+OT#6O|{@} zSWG3kS?*S>7cR|s%6VO7GJx320b_4ceEAl9c|<@d{xhbk7dtx zIH!<|;`3$;peoo)`d^XqkzLl0_02o}W{TBhQep_iEn|_r8`Rh^Dbcd0ekVv$lZ!*( zU%l=NJ_$7K1N%C8pNEoXu0V2w59cO{88@`nBq$Di z6Ozg$iejDMjbCE$l1E3FtR`!$Po>*cb%cE&n9cV}C*aE1iZI zqfW5?(rFR)|D}FTCQeTO3=sVX^@~xn`A7Y}W|d&f2^v5oT8+45K-vYe)@0uIic^9< zAp+e+Xoq9OX$N&A(E?F;1nT7T(NA+c1Mv#%TqPtMmx;a&G`g6Y?96t$HE!mGBPk{C z45Al83cjK^CqvclN1g-o*O`5jq;pOR6&K`flo^Ty*E*3fO$yVO4N1?8Xgs`7K)k#j zNmD>IWa?sI0tx+;e@$&gQ+OvqNi{@TP*_w{aS*zbMi0Aj_#s_4veNLYP&>EAGYk(z zR?zbf;Fd{LrX^3d{9#N@ zwLHuZ588cy$0{omP*%f)g$=1_IeOhCSWFmGw7GnJrTWAPSH#6g8x3N8M4nkZmtKO< zQb&c1TK3|PhxRIsRNvW}RIa^Tw-_63chZZHJY1NVuxI@6K`;DM_9f|CtwM6J(_TXo z?TDfnYgz;tvRM|aeuk7*rLkN?L`cg*df5TYo$ZU?;T$ix@$#hi#7=Agl&ep(;E@4{ zKD+>xlCcw>J1)GGfy>59o7n{q-c|iTQCW;!SsZ}sKT`7*GzfUKZz?So7KSIRaR$%m z7>iChINVM-O>`ReetnT>N5FXF-!&eAn!>Z&HxuQ)nSx#cq|=6D*N`#;+UUM_jSuq0 zOJ{=?)))QZll|gULlo~uSQU~eHQ2VXk04FEJMd}gbvn#+(2gdh0ff9p9izge23A@$ zz?Oa@9xiCeCiL{7<_VXKm=xv9!-GR4H>BWA321>$Q|1TzY@t=rb=9rRN|JE|Q64R>+!l zcHN=-p^xyO#E-&x9Cpw(bv!M;8Zvy`@NqmCj2p6TILKAqJFHeHcg@DC9Nn^*v?$Ou zr+w732|>07)x}d~P3rLmDl{7aTzLPLMYSO+Vro)7wdz}%>stF~h#{Mr%wh}{lk21v z3(~*TceVPfNHTEn&dcD>q@ozbJ`Ruf=j-F%c#+We8B7+fLj>hA!U9BQsO<}rZyz+T z+r~YPBIJ4BKmh-Y$u0;epr(G*D{ylz8zNYWX(q&@0oY8eP6B_KM|Bz~_XSbuK}&jM zMeS8iV*f=RpYIQ}w8b&}72&vi3!Nn8pChaH`(K_PQa$;jz~<9I$nPI*d=@#`I{J7( zQz6(GZ3OM{zw9KBNS46G&Ohxdg@1L>86H)uT+9(kGWKX6cr;_jRl%bdAZzHsmLW80 z4l^o+2*+VjoLza^C6C@bxAi`Mirdn$-U-SgYb_(1vWsHJec?{zN0L_=aXbr^J=qlp zwk*S%sRnjp_O^4!x*prwLDn|E=3upj3DIm_#<>vYyumxRsA9K*Ks$rBH251VQ4iPq zKkn}76Rl|PI{C)C5lp*OBOS%*qaM8~Oen(hTkl!x$#S&S8jfh8ISn4Z96+~v4h~c) zsT6?BIxsf!7)5+ZV7`1iNP-O8kuptMmnjz*vt9SDbmA^y!|@89av?HfGiB+p+Jzh| z(YdfOBHPwo9dN2hH|Iu1l6h8zq*rDYzRcjSM$%{_bXX~)Z^)E?@Gg8I>HtC|X6*v1 z+}dmPF^U#Q&8JW%R23omM4c&4K!k)NxQU%qwl?$t`2WZv5A61bZ*4utbg|fW98Y^e z0RLjg>mb~g@dR&8Oc*_`V<^3d5nJh*d5+$+c6Vmx=I(@(6}>Q{TXGEWEkt3)HgzOy zvaN=1C7;(|y~){K8nnPCiSV+r?@9YC)DL|?*T!WQBOXc=iM%)qJMak9rqB?k;w$-~ zg8aDZe$i}Y5cc{$>SB3xNvO%}-es%}B1j(*u_(QrVMj(woIlMUf+h0x!}zQ)LoKr) z4BPU^U`2o-W6(2qe+gJF@i90(Qtf+tks2KdwaS*v%bh-X7p=*Tcdm3fDQUD032zA< zeto98;yM#)sp;^`uP^i>>MD)b3@M+=|z%Tfd zv97bpPhdF!y1V`Gkn=N(&73kYL@`}^DsRFV38#_}KgOtO?j$Q}IxrrbO)Aiu+>lw7 zejHz{*zSxWf{pzTW~91X=kRawg$8mrAzgNg2Nbd+_oX%MiXG3$7tJa$I6s6=SS@bc z2&qXrt4PCCdF$vJs=av-xr9ZVRp)X$4&Qj!pfB1KXy zFG%Bh2WQ2Tp&-~Biq@BZ8=dHhiLZatoPs@><$D8|ci4ZF2X=eMS7>*9-KmE0c#(?@ zglqpDS19XTwVHbNY_>S8OJQU@ll7+Y31L42jDYuCR5huHX>zy7M#AjZ$R;A&4maly zLv0-JMCRMjjc_Reghr3ACkO5S&;rT^O^odqR9Z3LeqY z(y3F$`oe?IK+F(w^}st1QzqDJu8_J$N&pQ3QDSg`@E!WWMH%m;#WefD!&k)!;D<icvk0~i49G2UsBOY1*DBYEmZ3zDNddc?*?IS>lB!d?&Y_V){K4Yn(@xbZy47x@X# zK~nvvrzy=Ornn{=)6T1M&t6e5KKz5OnFZ(hZP&ShvUx{FI;e01Uf)XfTNc68P_4z6;xeIJH&QW9GlB0=P2%-%#hrus4|g@d&9nZU)9B@+xb4wMU( z-1|qQShS`!r_~t6@JYsG6;UI|ad3OqNDsGFSk39442eD7`jD@4s9mPcF!+4$jbH9& zcF=yB1D}fPzu1vgh`>9h(p2PY`H>EO~oUKaEG z@_E?W8`q}w6zSovy*m5&1+Gha^T~WJ8?SKRPhR@WGhT0V=>TjGVeNf7Q&mRZ&u*|T zjP$=4BzFBcc?dLqm8kmvh6bIEhs_?Kt(M%eV}13QaY`Ysss^U3=RU&0*WPtg7wK+B zxVt!!I`sMh_8@0hYvBPa==LqhQK3x8pmeWM|4X*}ZF)Ib)>U5DuxW;;)hM$Z-K8-4 z$XJiJX7FZfT3VlHSJ~7l{h<7quYt>fzTP&C-bm@KY5d-qXO^iybN8I*R-su9wh}@z z3iI~!&f~_Kk(I9yq%?!CuD@vNlQ$vOpP>l3{_f=E?%A63dU*DrPiV?9S{Y5k?F+5r zWyTuI>}13U4*pR^(In2Pzkx$FhX!ND8N-HK`;yvL%;mUga4D-Qs{!cm9eN(jU)gNq zFeVVMLcjRMZWl|Yyk~5~;VIWk3%^>!i?hHWNxqSB$281ziH;u@(3R_O9g3SbXQWcN za6q_yCF*bu z5RxL+@(~KBrAhD5wSbC>gsS;NxnzC?lL0zi9~}6SO2V2yU)+stRjog`Y8FV=zPxdQ z%7GCFu63|z&PHH~-DCQ+XN9_{iyy8{hU({Kfw9n!V~*OprVZNKnpo6=W5?P(+mNYa zptyZ|WEJ!20CaH>KMu{SIx)WGNyUQNwLFuI{%Frm2`f&tC?Dnbgb6~ezE7aQI@4Se z{aEz@4cayD_pb`mGU1$K@mFDD{+~3lceJyycm7WX)ACQcCW_#5qV|u$C`a@TNg@N* zBK~qcD1=;Cv%m}dt(!pQV3as{otPR!AktUBC!at2Rp~3hS77$nV3f0o=$?WIu1tqN6~EkReMJ{h`<~UqoFtxK4rQ+ad*=m6U68SQ|&T&pv{^}0W#+vDk7tn z3dtn|J0(&Clvr$UBnKHR;m-nHOS5-=M@qQlRB%diRfq%I)v*k?@uJqSYGjDhUz<^T zm36WiOJ!7bLiIw@G)t{FDgLn7zQ{f2Mi)T>NlQz+%>#3=VZ_pcTCAijVtgh@%P$!xf= znIU`eO&D3s446`zatCs;Xp`n}QIzMNV0DS7L?oHAPaoBTr*l#q_9DCidx&eC==fGD zCG_@4ceY*dDRFi&AOp4$MKI-QQf=ZAB2Utj!kJ17rSY}3vaN{C!B80Y@nrL zp1wY=LhUVS3p=+}p};+OMptw><JM!Id=#<~f`0&h9bP{+`k2l0hj8>`7 zLMK5^*aA5uGGS+M*U@YyV~Jpp=Gu#iv8l@H))Oyx9BAqQs*Pa^bxAu9ZG00q!+M$% z0J(Wy2v^WM0eEm zuS=mqQ)16OY7~U3bq9ER0F+g>?CAq}9%AvkoU|~Lh{v(4K<2jHz3Vw5c)&miq_XI-GAOtD58V;e5M14 z2JCYx2IYr5G1p)kj-criP?xR>GWm&207*tG+g`5{se{V4?whO3Q^dgWh4F#y^*>6R zlHE2GD?1F;%?VEsQ|J|Vj0cx@o*!%D5?)eKBE==I!2c+3gf_Hv@0q)~EqgNaLNU~U zeFI|FGAQXPrmV6F7Oezjg!r0T3l)utiDPF|B&xl7IcG-mm@K2t2KTl`_>OlLMSh5l z$g+-G?(gE@vIzmH;A;V zN;=?XY7|1UNWRoP;xIEPqJ@l0N4e5-37dstB3tDaN7p%k`w93e)4};GnDP`llpLs= zv`ew22OXtZkwngpg{H~rVIxzO)&&~Bjsq!F#+g`bGq_E%aTTr8Ji)%EsFzCy*hE7n z>Z)K)iSzO)iQwvtHP%g z96BvfYQqNeocz7Y(wJm;&P;2VgFV%U?I6dvRVb|QC)zG=(Uj)xO)P7xZ7^`T*2azD zUF*vts~c^3CYl~n)^|}Ptq0;alo9OG7x?2_Q44VA^aIoqK!vy=9d0H&l)Oa;Ea zuoxJWk@IwBsSvwxfZ?G2AsBnJ&GiKF{P%Nounwn$g3~vT!!&PYhj~QJ;k+1#e zlyD%FfJDFvVVuyv7eu%IX&M(I7j^6(9k>OefA=4ev5ox)L($R9+T_3caNM%8e>Hix zsy1#-IE45?!N8jCi6@XpYEb9kbj`_1PzjkYE8npM=!;HckgBcNym56GMxiDf#vdVv z03sX$fr}NOfwT|NG0nn@imobc3t}K@XcGs*wO^dAelI=VFRLn@ACNF&h*Kw)mgJ5R z%9)9IDE?U^?pSJBb~`31q$ik2SvJkDN_=ffb)iHOSP(N^x)Pc*G9b8iAjXC$N8q3} z79eSWg_8*BT)V1l;icu7FP|_fn7+#%;g~py*rrv};+B|(=-lw69-_KTM%OqtyH|J+ zd`)LKX;yAs>JY@tYK8O*s|!95@}+wWO& znuw81w5E@56_X_AyZwO09BW1a&fbHg?omG*BL?lH;JBmc9z$bGQ0QJU%)f106?R|# zP^y^dZO)ZD3y%0o4IZN5o+>PcNonVPQqRmNreByrpJ&wajsMPUHn2tBOawNFeVWxT z>GOBN!k8--GzG12JBqy!KFlb^DRU=w9OXI&W89#aIc@fe2KBVGszD0TrJ+pHe39wW zYd{!QV9J9b&9WEuGV-@{T{cY0gDhuuc=0~&3fj&GeS+(<1<9GY5b~UvWr%lF7l*LT zQi~?XfyGtzuGv;2hLz32<0ke_f2yWH8YHKABz{jaYb!QW&!Jjbm#tgcH!AD870;5~ ztw?ENvCOq$$N&xMA#VjBHMB|I9KuFS$g3)wu2*QWn&o8=5OQg=GRVSW)t7_WKvNpq zUhIB4VYTZF-};9%V>XW+^I+f(t@5<@kQOwa6{L=gHNsBcF-P!Bpx5ckuJuuHWVO*iRr5 z&156LJ$>uS&d!N7v|xFVU>6n+99g}0!LHe%Wq8}H^6?83UW)By-@3*1CeE#q6tTXw zc?ZO;^FGm8_r7Kkj7c#Jyp~prMm9$$l*Ur`ai>~}&|SO$rs8OmfACEoeD^x@60N_L z9k%F)5zLCrChEJBjK-93t_mf{10?5i^p$Yf)a#hi&8f z+09Vv2V8~^zG*L;Il1&~fP|4C&;vujoV}b_jj0I5h|nsF42?sAfWZAF;BLj&CR{un zm;bEs>+~7OkX9EIhq|Wp7aw8%pIfvGMpSh$2RJhmO|!FZFGJ=e(xRXf`c3(ft8Eu5 zQTyrD_9P^O#499>;kd7YFS{f_R)h(c+5rS-{vyNrFO;87=`l`YYjOtI0?G#!))0xZ z(eBQX_t*XOvfr6eOplHLZL7tTZtIA0Q@A%%Mu(s{>Z&`IRfQ3AgJ)E(!z)>B1}0&>ex4v21Ef?%1Ll zQk0Q3gz+d9gPU(lx;`aSG2=wI^awLZr8A&r1;!LS%6;AQ%HrM>bBg8jsM(azNh4u1 z*;uO_?)82JR@MOqDe}lh2`6!Sbqxj0esi- z?fw10;!jD40G(#p_;o z{rHgTLS?}at)wqcKy@L2U4TWj zKS3fvLQ7^Wwmb;$XczRY#E;U%kNdD|>XhwzSsX}35v0NB{ZAsKyfG<1?Xu_1x)ANO zvMLT!i)uT>qNZ>*o)9)UPI2so*?_%(OYREjyuZ3^eI-UR!6vh6^3EIFJsM?UL1$*w z4R~A&@TR=@!Q@q5+dl^3pZ2u6Y9_jPe13}O{$M$Q6;JK_w4(?s{u5yy-?%A|z~}PA_ZVR$+$<;4Q_tmRG1^E4{Ss)hdy%b%jJ9 zIiNZMg5Z}*(pt*AASI3Z<@#K33u&=>`$qHfKC8dKk^{oQuvqI z;n>G0WAQ}dYL<+EPAT%M#9_JYV8fwlfekLO!LQ>TlVUClLWd7xDAR!P2H8onBF2Hc zC(m!7#3GNL*~$!l7@AaSrsQVv_SEoMzD(Ph7Wylu=(x+Dsuhlk_=dQz1!iF5X87Dw zgg(<*il}emAb*Tk(V9D7ewsVdP(7WVZ@w{6ns)}N3+^=NN(yN_?^Qu}l&2+0O7MFa zqzhBj<>SEfC_C8W0&(VZaC&+&h8vp_?2l?8#=%G?MugD(`aO;JDN?i4CR3-TSqUu% z)`FM;^Hcvkkf?pGRpk7XS#WvvG0>2P)%PH02#Pv(ELA$IH;1_Ajg zpH_i8HmjO^{@RiiU^xDgdIvpTafe;_;st@otQlqu+gw;Y>n!H#)^w-S)P6(&$;Nx7 zwfbl-+Pb{FZYBzK0s$nC&dMyC1~>5@`SlXSLVmZlhO#{IrFHqVvO^-vQf^@tR1X(i zk9P2Tj!dzogO05H1^Qq!cG6humS~~AvAAsj5pWPzJO*x=F!HIGR3rS_f^ZwlS^L;E zl-cK?m7iB`NOIBIeEn|lp zkW1yfDDD{vAio4QrHRbVa1P135^YpJ^#4>Zy=W35)x@@G^lsZC$hyTJs`(7Zce7^$ zrJI5btvPdx6$)bqIcO#t+;q`yN?wj);^Sz`6!8$5v#_ z+}$ZzCcKfmvBRQ`c5GrHA=PCrG%rSQ6a5-sZUX_e7oQ}VgrK;9@MyClUI+Plw11-o zdK|!}rD+B2&rVk;=^2vNR*!5?NJk^;AxJeN1;l(F8bKn&0qcl>BX3AYK_vI26?IvD}x|;eYi-8vFG}fC$j2yI) zeqG@)^#Vi|2kg!k>V1g&y1}`IgDnsEVz_P*#O>Nhk2#^vJOpO_AkvwT#=Md!BQ{5EL7wJXd4=qTrn#{?Q-h)_ z8G>460j=SV#8yN3h#XBt#~C{`R2NFc6F*kL#u>RE)i+u?*%@bO!Y$1>0-!^gIT0Ppa-&*mnUg%$?d zTM;$~XdLS`=V$YnAxFXs_Bt6)#3{~(?7(%XN9x*ykWQ&39BVhsIwmqLo;(5>xyHnh zTTPVKLv5z}-jo(UH+xiW*u6}&7ULo9f=j7o1|{)0zqd$7CVZ#h0lnbv?Jeb+ERj!# zRmzPkl3rJ@@HeC|3GfDSL*8f7h%Y(hHYVGLkB$h?7`brT^LaBV184NEsuF#%_P2(@VI?zF^ZRZXneNf&paNuiksZlMF zAz3~A!Z?pyQNfn6VoTcAWraxfP(xR!cxg*5Lg}kCiqgm*8uc4>J}lG4jsa+6$FHk{0nDp0jct5 z$~Ewx%{G-YF9zadL}|SD-6}XuLRUPMLToUb@ukj8VV-n1aUn_7lziAppk<3Be8^zQ>v z8)i+FNF?4!jR37&um7>LNK_7r_3+VI#6|!BApTqGo{hePk-hUj6;}VdF#8+w-ajV1 zh0#6)P_ZX@Da^+| zDCC(k%P`t@a5Ff(beAhJ!~ls18K$51s#_}77YnR*BBuW?SW`YAKh4rm9?uwux3HX- zM5z`%dy^2u_hruq71F`X7=?RoKE61hlDMRO%#a3JBDb;nE9F^a&}QWLXhL;;aZ+J} zFtGq;WR z_2elPIM}@$PUgsl^y1rBoP zpnesVuS`r>|B^mQC^yL;D{QGua@MJ61YuqtX1VIxZ@3A;^*ImG{@@FwnXWlewmLi; zwH}nUKJ}a=x@(FkrJ}Lzc#Wh`#-du?P{tm>ZeQl?Bhbktxi9OknY~&0u!Ikn>D^MLM2nY2lxM#Tj(H2lCpAB1 zQP5%k9efu#4GP2!F(FGQRKP`5%!REq`kGFlG=fkS4!P!M1FinrdgJFegSlaUXM=FuU!j}ihT+BAvq@6a8Sj&)UZ&6k5P-S&<0f5lo!I07PK~#M+xuFg~TefTZ z>=pPBQ;~MW@kP9RJ+sy)F13F6-i$=(q8|n_5=-_Bb2kf+&e_1|J~87#;ehupTHS61 z)l@=<1u5K*;vzd=ZKHkCt$Bjt3F&n5x#T5QRviyx8`dcX5o%ZJL?g zbW=w=bH>Bd9;{H?k=aKY>7+4yJQ>j8)V%{Dm0B%^c}Q)PpX!El}?X-HT~R6;?m( zK@#8|0(Z_jT=Dw5q|TH-M8(#b*VCoVdoHXjpKX(q!FOv{p$=Ze^?H`*cJhStAR^>p zlkiWkEm3krn0HD9iJEvJ_HBw&ZZXDBPbyxvC12rM=@ZEGO@k;Qd6PE3+G)WNu7em> zu9IQ4dp!5~aNPRb-<@``Py_(B|VsBuVl;nEP&n3EPSkgAR@WWIQYXY(=@-w zQGk+EX}%FNI2{BQNy(1ZMi{5+jn#p5Io!?TCZ)cKbPdG;xro2j7ic8;Ez0RZoK1J2)bi8ROk&qMrI}m|5H3}0bB)n` zmy#0<_p;Yo)}TqIChXeq)`JcRn{n~<`n^?%YhGKMEs}C)yz|neO1HPIB(^tSXpB8o z(pXgPW}X~Ua#SrtS;~N#;`;9Tt&V-iZ6%OxjPwb0pvRaUA|V)Yw9BO*qCES@*%^(V z&j%4S0`HNnO!h4-c=uo=3~qstiP<8yhSe!vYaSDrj90UUwK@c6$w55+Rqi3MV0DYh zyX-Sy_Hd8w7%zhneH*0zI#z!Po{RE8Jc<|1>15b&8D>o(cHeA__ z6_&uNmopRHE-~_eKT|HbSSa5E<2ELzWkSjlDgzB=FNH4I6h`=(K&>-h6!l0QbG1lC zc;;2HsQwE(sgX5oLoREshZMy~LujI5?T)kpUBozg1x-WYB3BEdoN!l;V2WR;YvH3+ zqC%;Y;Q{xkjajS-L+bt$%>>%FbeKZi8{6WIx~v;_$H$j_k^P@}CWE{Ss>F_gA#orc zH||;B92_@gLfC85EtveST=0}8)XJDs%4IbR4(iLMZc@UMu6wzt zi_7~_Q2^ zs4MX6x?`~Ou-c2d9SPOO{@ zYwY0+v=?|)n(1PlJ4T~pV>jeB2!&CCQu3^VS3B{TSXNy@hbAX?Ti&S~b$;T+M=Wh#QdswV3hIlu7*0e9(ctX<#ns zHay^ShaPI@Zi##yfzU59L}xs9pYYZ&X3f33-WN=Lvw9*qL0gw{!uWrfsqXojRR2Vx z*a9&0K%d-Qa34>W?&9p@t2OLb=bB%q-oif0D#OME)3y*y;=+PHiog%lKsh&l(FCv+ z^Z@q0XV;L0Al_F6*9D>6V_7QItaHFe4zMLnpmi$+#>jLvwh6h$YH%R^2C`NMJ^)8+ zZwoOmr%G*$l^-I@S%VpEGMd>29)5{rFCPZvJ=-+-xr3OQM`s63xc3%&EgYHyw*z*K zz|rH1$HT5^R>ZT%ouhB_Vg!L9EBub9piW`s^*9LkEp&8-%rCU7vo*i<#`X492HtQb z>;39S*Sqf>JeXk;){CVNJnfxuA8^;tthaBYb}wHGTrq>hpY%TO@0xRVXnH?~i?bAr3S-Y~!(Nw&lq}i*RNR4CjU+OOV%0?xdYQUuz zLW7%ClS-w%tlS>7gxpN>B7dh#ZOkw*C>m>Iq7ZNO`FN$pg*bO!XY!Vkjj zj_-3|OO-AG83^t&#CnF_cr_!3d{xRZ{s*k~`|mXJdQ#-G3P4U43Ut zTZ|4v?Sbj^bho{bIYYL)6Sr~nWN&X3=v{e{wZ zc4put)eQ%o3jL+EGZVIE$^H(p%DK9$X$dz3bP%}qLG!6LcYSK`n-wXSiTbA*ScCFr z0u70PZ2-~Oom^I z%OEt<&GhM;mneIpi$G9Y@QzRU=)u0u?(V9IA)mo?T=2MtiwKc)a_4Wy*DC7UMRqV% z)hGX`!>%$v(~PysiHIyuPjDQh=;_}Ct3rH(e6V*+h1bL<$UM9d-K%9tpi!|!J`Cx_ zk+(F7SilZr4M({?MHzzYWlur5pg43r4BgdKN%VECD1~f(xEr>SI8F5Tz6+uY+7ZgJ zj}f%apUc0qcsb0-yo-!W?EAraWH6(z`uu=l&+4Z z`7tsViqwRpEdf&A_65bpUV;jwpte2eSp9xKo^RpgvR{Fy!=}AVd=5D zfn|Z?05<61{F0yrZ^|eI&%T*`hMu_1BQMc&JJ|SA>MfHhy`@MhGF1bka2P!&a3J-t zkUb@;VhRBeGTDE;Y!;I@NIM@fF(xjSv_YCqi%pU6Na=p8a^?YGaaZ|c~KV-G>r`3;|@Ols>=Mm zrIp`}$ck1@aHWuUwE1B;{=_sP$WxtG#Y`Xm{W*(AM`exa|PFzl61F6DRl9g+qO4xz^w^*FVuU{{+~+5}B+U-ComJw0 zs@^Gko7d#*%Mn2k-7elOD(``t%aOf~#!n`yHdo2=`yRR`hpG`2>FZPIgaC6CEWF5id<^2yt9Fs{n!AZt5FL11fJ^z*OQkroh6-a z&j#iNP@JX2vw*Xxf#o)NeQ+qXE$XgsF%PKSy?qGm;a!JJ3EjOMag-K@S+Sggszl2v zo5iEkLXsYW>Rd_cmH%+CwX}2EX;r_C)xCZ-z@Rdt=*3kt0j~{BD;Ofy4&flo!X>FR zeRP{+MH+w-!pl_$LShq6eWsy**43S}LXl0weJ~d^dbVh!Lmlg_2o3p;t&)IEiG^`D z)!joQ0gPsS&!39zR{b`m^)2(M=@x;WQp#I3_M)eoa@=xxtB=jAB-FO8DfvwOw6?)T zy){7KDnj?-J+}x6;!D;R*!VM;uLYM1@YkjFx#jO#IUtp7B(?$wT2t{NfW@##*D4#9TfFogO3{tsDbExYfY8-%kF(DdE~&VY!0L1*g7dF2&Q5%{$7+BgkINARvwtd5gMCG<1O6Ly+>;`=na% z^LR16h>tKk+sbTd_DojOO_(V3@W=r4G9aS%5+9=JB6bqM458<14wsMUccOvr zAt?k8qr`SdDOOzE?&|?rX0S5j+$oT7E7}PyuLTGI0e}h|XmZ)NS##I`?c=N3K<+tA z8nOL?1!obB07A+HF{V+q&2;WoMxQXpOOV3>kRi_7)11GhU0@{s`NZof6xx;)I;lS* zyxG`SI;KQv@l?R`o^9-~LsU+7P`^cU4FcK4uU6Dl*Oau8IqNev5j%p|7#lA4(7NyN ztZz&%#1^oZ0m8Vz^#FVU)!b0-POUm>bCJx_F!yD)lrt*|cvn10kP*(SM_%283{Ec2 zzPX7w$MTxQjLl`-0qK1RDC*Xtsi*7Ds;mVknnm{5 zUcYyaG*B9XsxeHwLCtSBx3_+uM@BG{uL^5Y0`Z;Oa$x}|I_nZl4Dbne&{d4q7r;T~ zqc_3zc!o8>=}ewZc1K6*^3Vm|ESUEK-?YKb#)=2NO5lazG(9nJcOAc+09yb2k~z(} z6Q9RKrfz07p?)>pIUc{uT#c}or!t^~muy9q1~uA<031TSza*|cKoQ(QMIOg$oTj_b zA0dQ-U!t$kNBymfMj-}Pkr|-WU+@@vm4FXge^41a@t!Su3x-8}r3g8Lt0CUB24|M| zh(Z1MiX1H)&UMiS(4G|(4iB^5Yp{?s!R#JN4J=%!_Uu)mXydB{sRjDP4!vv)RB5xR zACx1YJ(@GL+zNj(i$!V{0&~&@FkCT=ts73v_H!O=uT!v0eQ+Vp^%_gK|8a7esw#IY zALkvU0 zwg#W4*bowO3Poj-{=h^nJH*C+d1&57A8f#E`gWW z_V^-VXaTCjt!!2j7e<(hBc@Tg>El`!F&_uigv4lvhUHSuQNQ<-k+utp)F2u_Pj&ZZ z|Gw!NIQlNWvRRXp*x4M;3zOlYdh5sIU9=x3+^uEja(pwJXW+h;RS!Sa8ZA}AVYWQK zC!Nprl-{~6vO1qB@`@gT$jMT2HR;K0z2cN5!wp={N_|}z^wOd`zrqteCe;gwRzvSt zfUL>Mo-xHe%O$=xl*?#2l+56(D5tWKcWxzl{SNK=71ar{c^C^1&h zXBeF6D*X7CUA;6>S{dWr;9JxKf|Y4um%fD0uaCzz+Q_SRT}+=b0_>3eLcXjOs%jOk z=v);g#7$k~psyUnfP1jE-d7Z*^rUfSOz{*QrK^qIh;bZF_1WfCY^ZSTLaZHdzF} z1mPF3D(>dn*MG=#{PPh04|WQ_9h(1tb_&1Z!Y^xV#(ijO^?b;2lKkyqtY__LMs52+ z?liLh*Oc`ytA@Yme>SK}*{rZ4bv&z}EG>Atu3U-~B1!@ecGHoF!Eco#dcSSYRiMzQPP9GmG!OxHwFBt#C&q@98pC_kMR7RGQT-&~%*T{pteN>-3W zv|yPr=8oicmVbY9cS;UQ8oyapB<_lVMpCpi(!vNBrYXjt34yx>U5nyil;P9Z(9qFw zc-WIXQKhJL?SULOYT<6AMcg|#Hvz|)J+pJ~YGQJHb!AWC+0r28^M3E*PJTuAx}wPB zc4w%3RjSCSt`I|I7%{_m!$>AjJmlfAWXzv57j$`z{?J5f-jKxHZc?P(+5+(%>wVh? z>o8FymrrrS49&+Y-tu$JtBAT11vbtZ`~tD_jX+DjnCr=*f1UAQC)}ZJ*4sU42gYfU zt}A=4|J2!=w@Z|Y^gygQ>cPzp)vM?fJ5Pnwc+9*V^Jr7Eb}t9AAS@F+_;*O2r(c?uwVadde@JRp(#u|>>0+{+xz zM@fx!RdjiBuTqr58PX(T z=W|P$nw99}LFR6e*xF7`H)270<<(eY)x6n;`SSH?pnbFH$rZb&KU!x7cQ}!USq_Ka z&XJ*#1I}3homt+O&WjBM`%|p=!{{2(9i#*8-z>gdF%x-x3ofdbY1HL!Wc5!1cvie~ z4ZP?6vg$dc45ufX&<`Am5L!^_*+w1DmWJO0Pn=T~FxRFSmO@XU`{)-Q|1q>Cr%NzE zvPy6qIJ9ow5hluHbk8#gku@_2ga@{!Xa881h1uXL9`>5wqA380{Eyd1k6 zAXSf}m^l)E$qz3sD|h6YPRe+2Fp0K&)=_&DW<|NHzj-B!@|~Y0L(HGJuJVVy8E>DX zgtOOOpjrxZ9lzFkVv>IwWbG0Rg-rJuCszthke=G8Rxc<)!U%i+F~8YkJO}|+A4M3y zk+|?v``U_nL8Tfp-Vixz|DFDfLgp+GRUnF2W%_J{sCT9uw$!?VW@>vQ6fEI)EV+5C zUGLIe0l%fQCy_UYbz5%`8)u#%ozD|_*%Fmo-GNafXu;nuT)*^J%sI!HUvqVHIk=)F zqxR4QjG7_T1iZIA_u}{BkH6=E_&iQjsNbOVvILHLQQb5&x<1{L`h9W%+G+(W zrvOnu9e;DG6SEYrYrfP3%V7k5)g=aqIv6-JC4M15F#i*?lHC&dOD53PuorHAN=lCq;idIQnsv^IUd6vdx;TQXz^ZqlGb z)4@BTrCX5CYBX^G9MXlyWkiZTXW|MLw|tW^Mf2mJq6}2#ZqgIdY3eavSf~3e?wyno zQp7W4636&(;VX#ElB0YxI0b^nmq@Q?8fv0)xid^VgI~8^?mNoH0`{-3%eYp9J5J=$0LJvR2;g2#ST~E7@4V((9?c}!(;}qOmV{`HqVR7o z-*%$Dw^fbA)dQhf<*}hg3r16vXKU6s#wH(=j2Np$S_hX%3u|MxEhNw9qE=SFSVUD> z?qYYDv4tx}#^Im27+62-F45#0^q?*uAkfTOObU%HBJj30ky-H$Rs`i-dPWKhtSP0^ z$8`d0!hor8<0A}X<+TReu>cB@Aj3TLV}b~no#5I&^2ka60(}PlJ4S2bt@yQU3Mg z?gQg5eX@RiDF0lzKRadpo=Mc-V*HP9)(6Bd->iSLSbugI`5mGW{qNHF3(t}N4EAT` z_}{@~KK~uqU+c*KyU*xfU%Wrc&i;<)NAjQW{=pIWzrp-bfbVyhb?U!^`CoE;|2LpN zYAO8=aQ9a{#m@D?bgZaqkf3!6IZzzA9s{S2?_hS?L>kH`j8SDRy z^5?;~-%)@?{|@DUjlq2Y{ThS&Hy6^c@Ae<5oWBF5D*YYMpNO6RIj29 -## Quick Reference - -**The 3-Layer Pattern (ALWAYS follow this):** - -1. **Search** - Get index of results with IDs - ``` - search(query="...", limit=20, project="...") - ``` - Returns: Table with IDs, titles, dates (~50-100 tokens/result) - -2. **Timeline** - Get context around interesting results - ``` - timeline(anchor=, depth_before=3, depth_after=3, project="...") - ``` - Returns: Chronological context showing what was happening - -3. **Fetch** - Get full details ONLY for relevant IDs - ``` - get_observations(ids=[...]) # ALWAYS batch for 2+ items - ``` - Returns: Complete details (~500-1000 tokens/result) - -**Why:** 10x token savings. Never fetch full details without filtering first. - ---- - -# Memory Search - -Search past work across all sessions. Simple workflow: search ā†’ get IDs ā†’ fetch details by ID. - -## When to Use - -Use when users ask about PREVIOUS sessions (not current conversation): - -- "Did we already fix this?" -- "How did we solve X last time?" -- "What happened last week?" - -## The Workflow - -**ALWAYS follow this exact flow:** - -1. **Search** - Get an index of results with IDs -2. **Timeline** - Get context around top results to understand what was happening -3. **Review** - Look at titles/dates/context, pick relevant IDs -4. **Fetch** - Get full details ONLY for those IDs - -### Step 1: Search Everything - -Use the `search` MCP tool: - -**Required parameters:** - -- `query` - Search term -- `limit: 20` - You can request large indexes as necessary -- `project` - Project name (required) - -**Example:** - -``` -search(query="authentication", limit=20, project="my-project") -``` - -**Returns:** - -``` -| ID | Time | T | Title | Read | Work | -|----|------|---|-------|------|------| -| #11131 | 3:48 PM | šŸŸ£ | Added JWT authentication | ~75 | šŸ› ļø 450 | -| #10942 | 2:15 PM | šŸ”“ | Fixed auth token expiration | ~50 | šŸ› ļø 200 | -``` - -### Step 2: Get Timeline Context - -You MUST understand "what was happening" around a result. - -Use the `timeline` MCP tool: - -**Example with observation ID:** - -``` -timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project") -``` - -**Example with query (finds anchor automatically):** - -``` -timeline(query="authentication", depth_before=3, depth_after=3, project="my-project") -``` - -**Returns exactly `depth_before + 1 + depth_after` items** - observations, sessions, and prompts interleaved chronologically around the anchor. - -**When to use:** - -- User asks "what was happening when..." -- Need to understand sequence of events -- Want broader context around a specific observation - -### Step 3: Pick IDs - -Review the index results (and timeline if used). Identify which IDs are actually relevant. Discard the rest. - -### Step 4: Fetch by ID - -For each relevant ID, fetch full details using MCP tools: - -**Fetch multiple observations (ALWAYS use for 2+ IDs):** - -``` -get_observations(ids=[11131, 10942, 10855]) -``` - -**With ordering and limit:** - -``` -get_observations( - ids=[11131, 10942, 10855], - orderBy="date_desc", - limit=10, - project="my-project" -) -``` - -**Fetch single observation (only when fetching exactly 1):** - -``` -get_observation(id=11131) -``` - -**Fetch session:** - -``` -get_session(id=2005) # Just the number from S2005 -``` - -**Fetch prompt:** - -``` -get_prompt(id=5421) -``` - -**ID formats:** - -- Observations: Just the number (11131) -- Sessions: Just the number (2005) from "S2005" -- Prompts: Just the number (5421) - -**Batch optimization:** - -- **ALWAYS use `get_observations` for 2+ observations** -- 10-100x more efficient than individual fetches -- Single HTTP request vs N requests -- Returns all results in one response -- Supports ordering and filtering - -## Search Parameters - -**Basic:** - -- `query` - What to search for (required) -- `limit` - How many results (default 20) -- `project` - Filter by project name (required) - -**Filters (optional):** - -- `type` - Filter to "observations", "sessions", or "prompts" -- `dateStart` - Start date (YYYY-MM-DD or epoch timestamp) -- `dateEnd` - End date (YYYY-MM-DD or epoch timestamp) -- `obs_type` - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change - -## Examples - -**Find recent bug fixes:** - -Use the `search` MCP tool with filters: - -``` -search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project") -``` - -**Find what happened last week:** - -Use date filters: - -``` -search(type="observations", dateStart="2025-11-11", limit=20, project="my-project") -``` - -**Search everything:** - -Simple query search: - -``` -search(query="database migration", limit=20, project="my-project") -``` - -**Get detailed instructions:** - -Use the `help` tool to load full instructions on-demand: - -``` -help(topic="workflow") # Get 4-step workflow -help(topic="search_params") # Get parameters reference -help(topic="examples") # Get usage examples -help(topic="all") # Get complete guide -``` - -## Why This Workflow? - -**Token efficiency:** - -- **Search results:** ~50-100 tokens per result (table index) -- **Full observation:** ~500-1000 tokens each -- **10x savings** - only fetch full when you know it's relevant - -**Batch fetching:** - -- **Individual fetches:** 10 HTTP requests, ~5-10s latency -- **Batch fetch:** 1 HTTP request, ~0.5-1s latency -- **10-100x faster** for multi-observation queries - -**Clarity:** - -- See everything first (table index) -- Get timeline context around interesting results -- Pick what matters based on context -- Fetch details only for what you need (batch when possible) - ---- - -**Remember:** - -- ALWAYS get timeline context to understand what was happening -- ALWAYS use `get_observations` when fetching 2+ observations -- The workflow is optimized: search ā†’ timeline ā†’ batch fetch = 10-100x faster - ---- - -## Tool Reference - -Comprehensive parameter documentation for all memory tools. For MCP usage, call `help(topic="search")` to load specific tool docs. - -### search - -Search across all memory types (observations, sessions, prompts). - -**Parameters:** - -- `query` (string, optional) - Search term for full-text search -- `limit` (number, optional) - Maximum results to return. Default: 20, Max: 100 -- `offset` (number, optional) - Number of results to skip. Default: 0 -- `project` (string, required) - Project name to filter by -- `type` (string, optional) - Filter by type: "observations", "sessions", "prompts" -- `dateStart` (string, optional) - Start date filter (YYYY-MM-DD or epoch ms) -- `dateEnd` (string, optional) - End date filter (YYYY-MM-DD or epoch ms) -- `obs_type` (string, optional) - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change -- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc", "relevance" - -**Returns:** Table of results with IDs, timestamps, types, titles - -### timeline - -Get chronological context around a specific point in time or observation. - -**Parameters:** - -- `anchor` (number, optional) - Observation ID to center timeline around. If not provided, uses most recent result from query -- `query` (string, optional) - Search term to find anchor automatically (if anchor not provided) -- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20 -- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20 -- `project` (string, required) - Project name to filter by - -**Returns:** Exactly `depth_before + 1 + depth_after` items in chronological order, with observations, sessions, and prompts interleaved - -### get_recent_context - -Get the most recent observations from current or recent sessions. - -**Parameters:** - -- `limit` (number, optional) - Maximum observations to return. Default: 10, Max: 50 -- `project` (string, required) - Project name to filter by - -**Returns:** Recent observations in reverse chronological order - -### get_context_timeline - -Get timeline context around a specific observation ID. - -**Parameters:** - -- `anchor` (number, required) - Observation ID to center timeline around -- `depth_before` (number, optional) - Items before anchor. Default: 5, Max: 20 -- `depth_after` (number, optional) - Items after anchor. Default: 5, Max: 20 -- `project` (string, optional) - Project name to filter by - -**Returns:** Timeline items centered on the anchor observation - -### get_observation - -Fetch a single observation by ID with full details. - -**Parameters:** - -- `id` (number, required) - Observation ID to fetch - -**Returns:** Complete observation object with title, subtitle, narrative, facts, concepts, files, timestamps - -### get_observations - -Batch fetch multiple observations by IDs. Always prefer this over individual fetches for 2+ observations. - -**Parameters:** - -- `ids` (array of numbers, required) - Array of observation IDs to fetch -- `orderBy` (string, optional) - Sort order: "date_desc" (default), "date_asc" -- `limit` (number, optional) - Maximum observations to return. Default: no limit -- `project` (string, optional) - Project name to filter by - -**Returns:** Array of complete observation objects, 10-100x faster than individual fetches - -### get_session - -Fetch a single session by ID with metadata. - -**Parameters:** - -- `id` (number, required) - Session ID to fetch (just the number, not "S2005" format) - -**Returns:** Session object with ID, start time, end time, project, model info - -### get_prompt - -Fetch a single prompt by ID with full text. - -**Parameters:** - -- `id` (number, required) - Prompt ID to fetch - -**Returns:** Prompt object with ID, text, timestamp, session reference - -### help - -Load detailed instructions for specific topics or all documentation. - -**Parameters:** - -- `topic` (string, optional) - Specific topic to load: "workflow", "search", "timeline", "get_recent_context", "get_context_timeline", "get_observation", "get_observations", "get_session", "get_prompt", "all". Default: "all" - -**Returns:** Formatted documentation for the requested topic diff --git a/plugin/skills/mem-search/operations/.gitkeep b/plugin/skills/mem-search/operations/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/plugin/skills/mem-search/operations/by-concept.md b/plugin/skills/mem-search/operations/by-concept.md deleted file mode 100644 index 14f642f3..00000000 --- a/plugin/skills/mem-search/operations/by-concept.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search by Concept - -Find observations tagged with specific concepts. - -## When to Use - -- User asks: "What discoveries did we make?" -- User asks: "What patterns did we identify?" -- User asks: "What gotchas did we encounter?" -- Looking for observations with semantic tags - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&format=index&limit=5" -``` - -## Parameters - -- **concept** (required): Concept tag to search for - - `discovery` - New discoveries and insights - - `problem-solution` - Problems and their solutions - - `what-changed` - Change descriptions - - `how-it-works` - Explanations of mechanisms - - `pattern` - Identified patterns - - `gotcha` - Edge cases and gotchas - - `change` - General changes -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of observations by concept -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "concept": "discovery", - "count": 3, - "format": "index", - "results": [ - { - "id": 1240, - "type": "discovery", - "title": "Worker service uses PM2 for process management", - "subtitle": "Discovered persistent background worker pattern", - "created_at_epoch": 1699564800000, - "project": "claude-mem", - "concepts": ["discovery", "how-it-works"] - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 3 observations tagged with "discovery": - -šŸ”µ **#1240** Worker service uses PM2 for process management - > Discovered persistent background worker pattern - > Nov 9, 2024 ā€¢ claude-mem - > Tags: discovery, how-it-works - -šŸ”µ **#1241** FTS5 full-text search enables instant searches - > SQLite FTS5 virtual tables provide sub-100ms search - > Nov 9, 2024 ā€¢ claude-mem - > Tags: discovery, pattern -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Available Concepts - -| Concept | Description | When to Use | -|---------|-------------|-------------| -| `discovery` | New discoveries and insights | Finding what was learned | -| `problem-solution` | Problems and their solutions | Finding how issues were resolved | -| `what-changed` | Change descriptions | Understanding what changed | -| `how-it-works` | Explanations of mechanisms | Learning how things work | -| `pattern` | Identified patterns | Finding design patterns | -| `gotcha` | Edge cases and gotchas | Learning about pitfalls | -| `change` | General changes | Tracking modifications | - -## Error Handling - -**Missing concept parameter:** -```json -{"error": "Missing required parameter: concept"} -``` -Fix: Add the concept parameter - -**Invalid concept:** -```json -{"error": "Invalid concept: foobar. Valid concepts: discovery, problem-solution, what-changed, how-it-works, pattern, gotcha, change"} -``` -Fix: Use one of the valid concept values - -## Tips - -1. Use format=index first to see overview -2. Start with limit=5-10 to avoid token overload -3. Combine concepts with type filtering for precision -4. Use `discovery` for learning what was found during investigation -5. Use `problem-solution` for finding how past issues were resolved - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/by-file.md b/plugin/skills/mem-search/operations/by-file.md deleted file mode 100644 index d5daa887..00000000 --- a/plugin/skills/mem-search/operations/by-file.md +++ /dev/null @@ -1,127 +0,0 @@ -# Search by File - -Find all work related to a specific file path. - -## When to Use - -- User asks: "What changes to auth/login.ts?" -- User asks: "What work was done on this file?" -- User asks: "Show me the history of src/services/worker.ts" -- Looking for all observations that reference a file - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=src/services/worker-service.ts&format=index&limit=10" -``` - -## Parameters - -- **filePath** (required): File path to search for (supports partial matching) - - Full path: `src/services/worker-service.ts` - - Partial path: `worker-service.ts` - - Directory: `src/hooks/` -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of work on a file -- Finding IDs for deeper investigation -- Listing multiple changes -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific changes -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "filePath": "src/services/worker-service.ts", - "count": 8, - "format": "index", - "results": [ - { - "id": 1245, - "type": "refactor", - "title": "Simplified worker health check logic", - "subtitle": "Removed redundant PM2 status check", - "created_at_epoch": 1699564800000, - "project": "claude-mem", - "files": ["src/services/worker-service.ts", "src/services/worker-utils.ts"] - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 8 observations related to "src/services/worker-service.ts": - -šŸ”„ **#1245** Simplified worker health check logic - > Removed redundant PM2 status check - > Nov 9, 2024 ā€¢ claude-mem - > Files: worker-service.ts, worker-utils.ts - -šŸŸ£ **#1246** Added SSE endpoint for real-time updates - > Implemented Server-Sent Events for viewer UI - > Nov 8, 2024 ā€¢ claude-mem - > Files: worker-service.ts -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Partial Path Matching - -The file path parameter supports partial matching: - -```bash -# These all match "src/services/worker-service.ts" -curl -s "http://localhost:37777/api/search/by-file?filePath=worker-service.ts&format=index" -curl -s "http://localhost:37777/api/search/by-file?filePath=services/worker&format=index" -curl -s "http://localhost:37777/api/search/by-file?filePath=worker-service&format=index" -``` - -## Directory Searches - -Search for all work in a directory: - -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=src/hooks/&format=index&limit=20" -``` - -## Error Handling - -**Missing filePath parameter:** -```json -{"error": "Missing required parameter: filePath"} -``` -Fix: Add the filePath parameter - -**No results found:** -```json -{"filePath": "nonexistent.ts", "count": 0, "results": []} -``` -Response: "No observations found for 'nonexistent.ts'. Try a partial path or check the spelling." - -## Tips - -1. Use format=index first to see overview of all changes -2. Start with partial paths (e.g., filename only) for broader matches -3. Use full paths when you need specific file matches -4. Combine with dateStart to see recent changes: `?filePath=worker.ts&dateStart=2024-11-01` -5. Use directory searches to see all work in a module - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/by-type.md b/plugin/skills/mem-search/operations/by-type.md deleted file mode 100644 index b659283c..00000000 --- a/plugin/skills/mem-search/operations/by-type.md +++ /dev/null @@ -1,123 +0,0 @@ -# Search by Type - -Find observations by type: bugfix, feature, refactor, decision, discovery, or change. - -## When to Use - -- User asks: "What bugs did we fix?" -- User asks: "What features did we add?" -- User asks: "What decisions did we make?" -- Looking for specific types of work - -## Command - -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5" -``` - -## Parameters - -- **type** (required): One or more types (comma-separated) - - `bugfix` - Bug fixes - - `feature` - New features - - `refactor` - Code refactoring - - `decision` - Architectural/design decisions - - `discovery` - Discoveries and insights - - `change` - General changes -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of work by type -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "type": "bugfix", - "count": 5, - "format": "index", - "results": [ - { - "id": 1235, - "type": "bugfix", - "title": "Fixed token expiration edge case", - "subtitle": "Handled race condition in refresh flow", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list with type emojis: - -```markdown -Found 5 bugfixes: - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server - -šŸ”“ **#1236** Resolved memory leak in worker - > Fixed event listener cleanup - > Nov 8, 2024 ā€¢ worker-service -``` - -**Type Emojis:** -- šŸ”“ bugfix -- šŸŸ£ feature -- šŸ”„ refactor -- šŸ”µ discovery -- šŸ§  decision -- āœ… change - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Multiple Types - -To search for multiple types: - -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix,feature&format=index&limit=10" -``` - -## Error Handling - -**Missing type parameter:** -```json -{"error": "Missing required parameter: type"} -``` -Fix: Add the type parameter - -**Invalid type:** -```json -{"error": "Invalid type: foobar. Valid types: bugfix, feature, refactor, decision, discovery, change"} -``` -Fix: Use one of the valid type values - -## Tips - -1. Use format=index first to see overview -2. Start with limit=5-10 to avoid token overload -3. Combine with dateStart for recent work: `?type=bugfix&dateStart=2024-11-01` -4. Use project filtering when working on one codebase - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/common-workflows.md b/plugin/skills/mem-search/operations/common-workflows.md deleted file mode 100644 index d6f51419..00000000 --- a/plugin/skills/mem-search/operations/common-workflows.md +++ /dev/null @@ -1,251 +0,0 @@ -# Common Workflows - -Step-by-step guides for typical user requests using the search API. - -## Workflow 1: Understanding Past Work - -**User asks:** "What did we do last session?" or "Catch me up on recent work" - -**Steps:** - -1. **Get recent context** (fastest path): -```bash -curl -s "http://localhost:37777/api/context/recent?limit=3" -``` - -2. **Present as narrative:** -```markdown -## Recent Work - -### Session #545 - Nov 9, 2024 -Implemented JWT authentication system - -**Completed:** -- Added token-based auth with refresh tokens -- Created JWT signing and verification logic - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions -``` - -**Why this workflow:** -- Single request gets both sessions and observations -- Optimized for "catch me up" questions -- ~1,500-2,500 tokens for 3 sessions - ---- - -## Workflow 2: Finding Specific Bug Fixes - -**User asks:** "What bugs did we fix?" or "Show me recent bug fixes" - -**Steps:** - -1. **Search by type** (index format first): -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5" -``` - -2. **Review index results**, identify relevant items - -3. **Get full details** for specific bugs: -```bash -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=full&limit=1&offset=2" -``` - -4. **Present findings:** -```markdown -Found 5 bug fixes: - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server - -[Click for full details on #1235] -``` - -**Why this workflow:** -- Progressive disclosure: index first, full details selectively -- Type-specific search is more efficient than generic search -- ~250-500 tokens for index, ~750-1000 per full detail - ---- - -## Workflow 3: Understanding File History - -**User asks:** "What changes to auth/login.ts?" or "Show me work on this file" - -**Steps:** - -1. **Search by file** (index format): -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=index&limit=10" -``` - -2. **Review chronological changes** - -3. **Get full details** for specific changes: -```bash -curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=full&limit=1&offset=3" -``` - -4. **Present as file timeline:** -```markdown -## History of auth/login.ts - -šŸŸ£ **#1230** Added JWT authentication (Nov 9) -šŸ”“ **#1235** Fixed token expiration bug (Nov 9) -šŸ”„ **#1240** Refactored auth flow (Nov 8) -``` - -**Why this workflow:** -- File-specific search finds all related work -- Index format shows chronological overview -- Selective full details for deep dives - ---- - -## Workflow 4: Timeline Investigation - -**User asks:** "What was happening when we deployed?" or "Show me context around that bug fix" - -**Steps:** - -1. **Find the event** using search: -```bash -curl -s "http://localhost:37777/api/search/observations?query=deployment&format=index&limit=5" -``` - -2. **Note observation ID** (e.g., #1234) - -3. **Get timeline context**: -```bash -curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10" -``` - -4. **Present as chronological narrative:** -```markdown -## Timeline: Deployment - -### Before (10 records) -**2:45 PM** - šŸŸ£ Prepared deployment scripts -**2:50 PM** - šŸ’¬ User asked: "Are we ready to deploy?" - -### ā­ Anchor Point (2:55 PM) -šŸŽÆ **Observation #1234**: Deployed to production - -### After (10 records) -**3:00 PM** - šŸ”“ Fixed post-deployment routing issue -``` - -**Why this workflow:** -- Timeline shows temporal context (what happened before/after) -- Captures causality between events -- All record types (observations, sessions, prompts) interleaved - ---- - -## Workflow 5: Quick Timeline (One Request) - -**User asks:** "Timeline of authentication work" - -**Steps:** - -1. **Use timeline-by-query** (auto mode): -```bash -curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10" -``` - -2. **Present timeline directly:** -```markdown -## Timeline: Authentication - -**Best Match:** šŸŸ£ Observation #1234 - Implemented JWT authentication - -### Context (21 records) -[... timeline around best match ...] -``` - -**Why this workflow:** -- Single request combines search + timeline -- Fastest path when query is specific -- Auto mode uses top result as anchor - -**Alternative:** Use interactive mode for broad queries: -```bash -curl -s "http://localhost:37777/api/timeline/by-query?query=auth&mode=interactive&limit=5" -``` -Then choose anchor manually. - ---- - -## Workflow 6: Search Composition - -**User asks:** "What features did we add to the authentication system recently?" - -**Steps:** - -1. **Combine filters** for precision: -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateStart=2024-11-01&format=index&limit=10" -``` - -2. **Review filtered results** - -3. **Get full details** for relevant features: -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&format=full&limit=1&offset=2" -``` - -4. **Present findings:** -```markdown -Found 10 authentication features added in November: - -šŸŸ£ **#1234** Implemented JWT authentication (Nov 9) -šŸŸ£ **#1236** Added refresh token rotation (Nov 9) -šŸŸ£ **#1238** Implemented OAuth2 flow (Nov 7) -``` - -**Why this workflow:** -- Multiple filters narrow results before requesting full details -- Type + query + dateStart/dateEnd = precise targeting -- Progressive disclosure: index first, full details selectively - ---- - -## Workflow Selection Guide - -| User Request | Workflow | Operation | Token Cost | -|--------------|----------|-----------|------------| -| "What did we do last session?" | #1 | recent-context | 1,500-2,500 | -| "What bugs did we fix?" | #2 | by-type | 500-3,000 | -| "What changes to file.ts?" | #3 | by-file | 500-3,000 | -| "What was happening then?" | #4 | search ā†’ timeline | 3,500-6,000 | -| "Timeline of X work" | #5 | timeline-by-query | 3,000-4,000 | -| "Recent features added?" | #6 | observations + filters | 500-3,000 | - -## General Principles - -1. **Start with index format** - Always use `format=index` first -2. **Use specialized tools** - by-type, by-file, by-concept when applicable -3. **Compose operations** - Combine search + timeline for investigations -4. **Filter early** - Use type, dateStart/dateEnd, project to narrow before expanding -5. **Progressive disclosure** - Load full details only for relevant items - -## Token Budget Awareness - -**Quick queries** (500-1,500 tokens): -- Recent context (limit=3) -- Index search (limit=5-10) -- Filtered searches - -**Medium queries** (1,500-4,000 tokens): -- Recent context (limit=5-10) -- Full details (3-5 items) -- Timeline (depth 10/10) - -**Deep queries** (4,000-8,000 tokens): -- Timeline (depth 20/20) -- Full details (10+ items) -- Multiple composed operations - -Always start with minimal token investment, expand only when needed. diff --git a/plugin/skills/mem-search/operations/formatting.md b/plugin/skills/mem-search/operations/formatting.md deleted file mode 100644 index 1b26c502..00000000 --- a/plugin/skills/mem-search/operations/formatting.md +++ /dev/null @@ -1,403 +0,0 @@ -# Response Formatting Guidelines - -How to present search results to users for maximum clarity and usefulness. - -## General Principles - -1. **Progressive disclosure** - Show index results first, full details on demand -2. **Visual hierarchy** - Use emojis, bold, and structure for scannability -3. **Context-aware** - Tailor presentation to user's question -4. **Actionable** - Include IDs for follow-up queries -5. **Token-efficient** - Balance detail with token budget - ---- - -## Format: Index Results - -**When to use:** First response to searches, overviews, multiple results - -**Structure:** -```markdown -Found {count} results for "{query}": - -{emoji} **#{id}** {title} - > {subtitle} - > {date} ā€¢ {project} -``` - -**Example:** -```markdown -Found 5 results for "authentication": - -šŸŸ£ **#1234** Implemented JWT authentication - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -šŸ”“ **#1235** Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server -``` - -**Type Emojis:** -- šŸ”“ bugfix -- šŸŸ£ feature -- šŸ”„ refactor -- šŸ”µ discovery -- šŸ§  decision -- āœ… change -- šŸŽÆ session -- šŸ’¬ prompt - -**What to include:** -- āœ… ID (for follow-up) -- āœ… Type emoji -- āœ… Title -- āœ… Subtitle (if available) -- āœ… Date (human-readable) -- āœ… Project name -- āŒ Don't include full narrative/facts/files in index format - ---- - -## Format: Full Results - -**When to use:** User requests details, specific items selected from index - -**Structure:** -```markdown -## {emoji} {type} #{id}: {title} - -**Summary:** {subtitle} - -**What happened:** -{narrative} - -**Key Facts:** -- {fact1} -- {fact2} - -**Files modified:** -- {file1} -- {file2} - -**Concepts:** {concepts} - -**Date:** {human_readable_date} -**Project:** {project} -``` - -**Example:** -```markdown -## šŸŸ£ Feature #1234: Implemented JWT authentication - -**Summary:** Added token-based auth with refresh tokens - -**What happened:** -Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm and proper key rotation infrastructure. - -**Key Facts:** -- Access tokens use 15-minute expiration -- Refresh tokens stored in httpOnly cookies -- RS256 algorithm with key rotation support -- Token refresh endpoint handles race conditions gracefully - -**Files modified:** -- src/auth/jwt.ts (created) -- src/auth/refresh.ts (created) -- src/middleware/auth.ts (modified) - -**Concepts:** how-it-works, pattern - -**Date:** November 9, 2024 at 2:55 PM -**Project:** api-server -``` - -**What to include:** -- āœ… Full title with emoji and ID -- āœ… Summary/subtitle -- āœ… Complete narrative -- āœ… All key facts -- āœ… All files (with status: created/modified/deleted) -- āœ… Concepts/tags -- āœ… Precise timestamp -- āœ… Project name - ---- - -## Format: Timeline Results - -**When to use:** Temporal investigations, "what was happening" questions - -**Structure:** -```markdown -## Timeline: {anchor_description} - -### Before ({count} records) - -**{time}** - {emoji} {type} #{id}: {title} -**{time}** - {emoji} {type} #{id}: {title} - -### ā­ Anchor Point ({time}) -{emoji} **{type} #{id}**: {title} - -### After ({count} records) - -**{time}** - {emoji} {type} #{id}: {title} -**{time}** - {emoji} {type} #{id}: {title} -``` - -**Example:** -```markdown -## Timeline: Deployment - -### Before (10 records) - -**2:30 PM** - šŸŸ£ #1230: Prepared deployment scripts -**2:45 PM** - šŸ”„ #1232: Updated configuration files -**2:50 PM** - šŸ’¬ User asked: "Are we ready to deploy?" - -### ā­ Anchor Point (2:55 PM) -šŸŽÆ **Session #545**: Deployed to production - -### After (10 records) - -**3:00 PM** - šŸ”“ #1235: Fixed post-deployment routing issue -**3:10 PM** - šŸ”µ #1236: Discovered caching behavior in production -**3:15 PM** - šŸ§  #1237: Decided to add health check endpoint -``` - -**What to include:** -- āœ… Chronological ordering (oldest to newest) -- āœ… Human-readable times (not epochs) -- āœ… Clear anchor point marker (ā­) -- āœ… Mix of all record types (observations, sessions, prompts) -- āœ… Concise titles (not full narratives) -- āœ… Type emojis for quick scanning - ---- - -## Format: Session Summaries - -**When to use:** Recent context, "what did we do" questions - -**Structure:** -```markdown -## Recent Work on {project} - -### šŸŽÆ Session #{id} - {date} - -**Request:** {user_request} - -**Completed:** -- {completion1} -- {completion2} - -**Key Learning:** {learning} - -**Observations:** -- {emoji} **#{obs_id}** {obs_title} - - Files: {file_list} -``` - -**Example:** -```markdown -## Recent Work on api-server - -### šŸŽÆ Session #545 - November 9, 2024 - -**Request:** Add JWT authentication with refresh tokens - -**Completed:** -- Implemented token-based auth with refresh logic -- Added JWT signing and verification -- Created refresh token rotation - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions - -**Observations:** -- šŸŸ£ **#1234** Implemented JWT authentication - - Files: jwt.ts, refresh.ts, middleware/auth.ts -- šŸ”“ **#1235** Fixed token expiration edge case - - Files: refresh.ts -``` - -**What to include:** -- āœ… Session ID and date -- āœ… Original user request -- āœ… What was completed (bulleted list) -- āœ… Key learnings/insights -- āœ… Linked observations with file lists -- āœ… Clear hierarchy (session ā†’ observations) - ---- - -## Format: User Prompts - -**When to use:** "What did I ask" questions, prompt searches - -**Structure:** -```markdown -Found {count} user prompts: - -šŸ’¬ **Prompt #{id}** (Session #{session_id}) - > "{preview_text}" - > {date} ā€¢ {project} -``` - -**Example:** -```markdown -Found 5 user prompts about "authentication": - -šŸ’¬ **Prompt #1250** (Session #545) - > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..." - > Nov 9, 2024 ā€¢ api-server - -šŸ’¬ **Prompt #1251** (Session #546) - > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?" - > Nov 8, 2024 ā€¢ api-server -``` - -**What to include:** -- āœ… Prompt ID -- āœ… Session ID (for context linking) -- āœ… Preview text (200 chars for index, full text for full format) -- āœ… Date and project -- āœ… Quote formatting for prompt text - ---- - -## Error Responses - -**No results found:** -```markdown -No results found for "{query}". Try: -- Different search terms -- Broader keywords -- Checking spelling -- Using partial paths (for file searches) -``` - -**Service unavailable:** -```markdown -The search service isn't available. Check if the worker is running: - -```bash -npm run worker:status -``` - -If the worker is stopped, restart it: - -```bash -npm run worker:restart -``` -``` - -**Invalid parameters:** -```markdown -Invalid search parameters: -- {parameter}: {error_message} - -See the [API help](help.md) for valid parameter options. -``` - ---- - -## Context-Aware Presentation - -Tailor formatting to user's question: - -**"What bugs did we fix?"** -ā†’ Use index format, emphasize date/type, group by recency - -**"How did we implement X?"** -ā†’ Use full format for best match, include complete narrative and files - -**"What was happening when..."** -ā†’ Use timeline format, emphasize chronology and causality - -**"Catch me up on recent work"** -ā†’ Use session summary format, focus on high-level accomplishments - ---- - -## Token Budget Guidelines - -**Minimal presentation (~100-200 tokens):** -- Index format with 3-5 results -- Compact list structure -- Essential metadata only - -**Standard presentation (~500-1,000 tokens):** -- Index format with 10-15 results -- Include subtitles and context -- Clear formatting and emojis - -**Detailed presentation (~1,500-3,000 tokens):** -- Full format for 2-3 items -- Complete narratives and facts -- Timeline with 20-30 records - -**Comprehensive presentation (~5,000+ tokens):** -- Multiple full results -- Deep timelines (40+ records) -- Session summaries with observations - -Always start minimal, expand only when needed. - ---- - -## Markdown Best Practices - -1. **Use headers (##, ###)** for hierarchy -2. **Bold important elements** (IDs, titles, dates) -3. **Quote user text** (prompts, questions) -4. **Bullet lists** for facts and files -5. **Code blocks** for commands and examples -6. **Emojis** for type indicators -7. **Horizontal rules (---)** for section breaks -8. **Blockquotes (>)** for subtitles and previews - ---- - -## Examples by Use Case - -### Use Case 1: Quick Overview -User: "What did we do last session?" - -```markdown -## Recent Work - -### šŸŽÆ Session #545 - November 9, 2024 -Implemented JWT authentication system - -**Key accomplishment:** Added token-based auth with refresh tokens -**Key learning:** JWT expiration requires careful handling of refresh race conditions -``` - -### Use Case 2: Specific Investigation -User: "How did we implement JWT authentication?" - -```markdown -## šŸŸ£ Feature #1234: Implemented JWT authentication - -**What happened:** -Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm. - -**Files:** -- src/auth/jwt.ts (created) -- src/auth/refresh.ts (created) -- src/middleware/auth.ts (modified) - -**Key insight:** Refresh race conditions require atomic token exchange logic. -``` - -### Use Case 3: Timeline Investigation -User: "What was happening around the deployment?" - -```markdown -## Timeline: Deployment - -[... chronological timeline with before/after context ...] -``` - -Choose presentation style based on user's question and information needs. diff --git a/plugin/skills/mem-search/operations/help.md b/plugin/skills/mem-search/operations/help.md deleted file mode 100644 index 7125d0af..00000000 --- a/plugin/skills/mem-search/operations/help.md +++ /dev/null @@ -1,171 +0,0 @@ -# API Help - -Get comprehensive API documentation for all search endpoints. - -## When to Use - -- User asks: "What search operations are available?" -- User asks: "How do I use the search API?" -- Need reference documentation for endpoints -- Want to see all available parameters - -## Command - -```bash -curl -s "http://localhost:37777/api/help" -``` - -## Response Structure - -Returns complete API documentation: - -```json -{ - "version": "6.5.0", - "base_url": "http://localhost:37777/api", - "endpoints": [ - { - "path": "/search/observations", - "method": "GET", - "description": "Search observations using full-text search", - "parameters": [ - { - "name": "query", - "required": true, - "type": "string", - "description": "Search terms" - }, - { - "name": "format", - "required": false, - "type": "string", - "default": "full", - "options": ["index", "full"], - "description": "Response format" - } - ], - "example": "curl -s \"http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5\"" - } - ] -} -``` - -## How to Present Results - -Present as reference documentation: - -```markdown -## claude-mem Search API Reference - -Base URL: `http://localhost:37777/api` - -### Search Operations - -**1. Search Observations** -- **Endpoint:** `GET /search/observations` -- **Description:** Search observations using full-text search -- **Parameters:** - - `query` (required, string): Search terms - - `format` (optional, string): "index" or "full" (default: "full") - - `limit` (optional, number): Max results (default: 20, max: 100) -- **Example:** - ```bash - curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" - ``` - -[... continue for all endpoints ...] -``` - -## Endpoint Categories - -The API help response organizes endpoints by category: - -1. **Full-Text Search** - - `/search/observations` - - `/search/sessions` - - `/search/prompts` - -2. **Filtered Search** - - `/search/by-type` - - `/search/by-concept` - - `/search/by-file` - -3. **Context Retrieval** - - `/context/recent` - - `/timeline/context` - - `/timeline/by-query` - -4. **Utilities** - - `/help` - -## Common Parameters - -Many endpoints share these parameters: - -- **format**: "index" (summary) or "full" (complete details) -- **limit**: Number of results to return -- **offset**: Number of results to skip (for pagination) -- **project**: Filter by project name -- **dateStart/dateEnd**: Filter by date range - - `dateStart`: Start date (YYYY-MM-DD or epoch timestamp) - - `dateEnd`: End date (YYYY-MM-DD or epoch timestamp) - -## Error Handling - -**Worker not running:** -Connection refused error. Response: "The search API isn't available. Check if worker is running: `npm run worker:status`" - -**Invalid endpoint:** -```json -{"error": "Not found"} -``` -Response: "Invalid API endpoint. Use /api/help to see available endpoints." - -## Tips - -1. Save help response for reference during investigation -2. Use examples as starting point for your queries -3. Check required parameters before making requests -4. Refer to format options for each endpoint -5. All endpoints use GET method with query parameters - -**Token Efficiency:** -- Help response: ~2,000-3,000 tokens (complete API reference) -- Use sparingly - refer to operation-specific docs instead -- Keep help response cached for repeated reference - -## When to Use Help - -**Use help when:** -- Starting to use the search API -- Need complete parameter reference -- Forgot which endpoints are available -- Want to see all options at once - -**Don't use help when:** -- You know which operation you need (use operation-specific docs) -- Just need examples (use common-workflows.md) -- Token budget is limited (help is comprehensive) - -## Alternative to Help Endpoint - -Instead of calling `/api/help`, you can: - -1. **Use SKILL.md** - Quick decision guide with operation links -2. **Use operation docs** - Detailed guides for specific endpoints -3. **Use common-workflows.md** - Step-by-step examples -4. **Use formatting.md** - Response presentation templates - -The help endpoint is most useful when you need complete API reference in one response. - -## API Versioning - -The help response includes version information: - -```json -{ - "version": "6.5.0" -} -``` - -Check version to ensure compatibility with documentation. diff --git a/plugin/skills/mem-search/operations/observations.md b/plugin/skills/mem-search/operations/observations.md deleted file mode 100644 index df5a7e1b..00000000 --- a/plugin/skills/mem-search/operations/observations.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search Observations (Semantic + Full-Text Hybrid) - -Search all observations using natural language queries. - -## When to Use - -- User asks: "How did we implement authentication?" -- User asks: "What bugs did we fix?" -- User asks: "What features did we add?" -- Looking for past work by keyword or topic - -## Command - -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (optional): Natural language search query - uses semantic search (ChromaDB) for ranking with SQLite FTS5 fallback (e.g., "authentication", "bug fix", "database migration"). Can be omitted for filter-only searches. -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - `dateStart` and/or `dateEnd` (YYYY-MM-DD format or epoch timestamp) -- **obs_type**: Filter by observation type (comma-separated): bugfix, feature, refactor, decision, discovery, change (optional) -- **concepts**: Filter by concept tags (comma-separated, optional) -- **files**: Filter by file paths (comma-separated, optional) - -**Important**: When omitting `query`, you MUST provide at least one filter (project, dateStart/dateEnd, obs_type, concepts, or files) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews -- Finding IDs for deeper investigation -- Listing multiple results -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete details including narrative, facts, files, concepts -- Understanding the full context of specific observations -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server", - "score": 0.95 - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 5 results for "authentication": - -1. **#1234** [feature] Implemented JWT authentication - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -2. **#1235** [bugfix] Fixed token expiration edge case - > Handled race condition in refresh flow - > Nov 9, 2024 ā€¢ api-server -``` - -**Include:** ID (for follow-up), type emoji (šŸ”“ bugfix, šŸŸ£ feature, šŸ”„ refactor, šŸ”µ discovery, šŸ§  decision, āœ… change), title, subtitle, date, project. - -For complete formatting guidelines, see formatting.md (documentation coming soon). - -## Filter-Only Examples - -Search without query text (direct SQLite filtering): - -```bash -# Get all observations from November 2025 -curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-01&format=index" - -# Get all bug fixes from a specific project -curl -s "http://localhost:37777/api/search?type=observations&obs_type=bugfix&project=api-server&format=index" - -# Get all observations from last 7 days -curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-11&format=index" -``` - -## Error Handling - -**Missing query and filters:** -```json -{"error": "Either query or filters required for search"} -``` -Fix: Provide either a query parameter OR at least one filter (project, dateStart/dateEnd, obs_type, concepts, files) - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No results found for 'foobar'. Try different search terms." - -## Tips - -1. Be specific: "authentication JWT" > "auth" -2. Start with format=index and limit=5-10 -3. Use project filtering when working on one codebase -4. If no results, try broader terms or check spelling - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) diff --git a/plugin/skills/mem-search/operations/prompts.md b/plugin/skills/mem-search/operations/prompts.md deleted file mode 100644 index 3aa91609..00000000 --- a/plugin/skills/mem-search/operations/prompts.md +++ /dev/null @@ -1,125 +0,0 @@ -# Search User Prompts (Full-Text) - -Search raw user prompts to find what was actually asked across all sessions. - -## When to Use - -- User asks: "What did I ask about authentication?" -- User asks: "Find my question about database migrations" -- User asks: "When did I ask about testing?" -- Looking for specific user questions or requests - -## Command - -```bash -curl -s "http://localhost:37777/api/search/prompts?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (required): Search terms (e.g., "authentication", "how do I", "bug fix") -- **format**: "index" (truncated prompts) or "full" (complete prompt text). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of what was asked -- Finding prompt IDs for full text -- Listing multiple prompts -- **Token cost: ~50-100 per result (truncated to 200 chars)** - -**Use format=full for:** -- Complete prompt text -- Understanding the full user request -- **Token cost: Variable (depends on prompt length, typically 100-300 tokens)** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1250, - "session_id": "S545", - "prompt_preview": "How do I implement JWT authentication with refresh tokens? I need to handle token expiration...", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 5 user prompts about "authentication": - -šŸ’¬ **Prompt #1250** (Session #545) - > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..." - > Nov 9, 2024 ā€¢ api-server - -šŸ’¬ **Prompt #1251** (Session #546) - > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?" - > Nov 8, 2024 ā€¢ api-server -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## What Gets Searched - -User prompts search covers: -- All user messages sent to Claude Code -- Raw text as typed by the user -- Multi-turn conversations (each message is a separate prompt) -- Questions, requests, commands, and clarifications - -## Error Handling - -**Missing query parameter:** -```json -{"error": "Missing required parameter: query"} -``` -Fix: Add the query parameter - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No user prompts found for 'foobar'. Try different search terms." - -## Tips - -1. Use exact phrases in quotes: `?query="how do I"` for precise matches -2. Start with format=index to see preview, then get full text if needed -3. Use dateStart to find recent questions: `?query=bug&dateStart=2024-11-01` -4. Prompts show what was asked, sessions/observations show what was done -5. Combine with session search to see both question and answer - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result, prompt truncated to 200 chars) -- Use format=full only for relevant items (100-300 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Prompts vs Sessions - -**Use prompts search when:** -- Looking for specific user questions -- Trying to remember what was asked -- Finding original request wording - -**Use sessions search when:** -- Looking for what was accomplished -- Understanding work summaries -- Getting high-level context - -**Combine both when:** -- Understanding the full conversation (what was asked + what was done) -- Investigating how a request was interpreted diff --git a/plugin/skills/mem-search/operations/recent-context.md b/plugin/skills/mem-search/operations/recent-context.md deleted file mode 100644 index dbf4e4b9..00000000 --- a/plugin/skills/mem-search/operations/recent-context.md +++ /dev/null @@ -1,134 +0,0 @@ -# Get Recent Context - -Get recent session summaries and observations for a project. - -## When to Use - -- User asks: "What did we do last session?" -- User asks: "What have we been working on recently?" -- User asks: "Catch me up on recent work" -- Starting a new session and need context - -## Command - -```bash -curl -s "http://localhost:37777/api/context/recent?project=api-server&limit=3" -``` - -## Parameters - -- **project**: Project name (defaults to current working directory basename) -- **limit**: Number of recent sessions to retrieve (default: 3, max: 10) - -## Response Structure - -Returns combined context from recent sessions: - -```json -{ - "project": "api-server", - "limit": 3, - "sessions": [ - { - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "request": "Add JWT authentication with refresh tokens", - "completion": "Implemented token-based auth with refresh logic", - "learnings": "JWT expiration requires careful handling of refresh race conditions", - "created_at_epoch": 1699564800000, - "observations": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "files": ["src/auth/jwt.ts", "src/auth/refresh.ts"] - } - ] - } - ] -} -``` - -## How to Present Results - -Present as a chronological narrative: - -```markdown -## Recent Work on api-server - -### Session #545 - Nov 9, 2024 -**Request:** Add JWT authentication with refresh tokens - -**Completed:** -- Implemented token-based auth with refresh logic -- Added JWT signing and verification -- Created refresh token rotation - -**Key Learning:** JWT expiration requires careful handling of refresh race conditions - -**Observations:** -- šŸŸ£ **#1234** Implemented JWT authentication - - Files: jwt.ts, refresh.ts -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Default Project Detection - -If no project parameter is provided, uses current working directory: - -```bash -# Auto-detects project from current directory -curl -s "http://localhost:37777/api/context/recent?limit=3" -``` - -## Error Handling - -**No sessions found:** -```json -{"project": "new-project", "sessions": []} -``` -Response: "No recent sessions found for 'new-project'. This might be a new project." - -**Worker not running:** -Connection refused error. Inform user to check if worker is running: `npm run worker:status` - -## Tips - -1. Start with limit=3 for quick overview (default) -2. Increase to limit=5-10 for deeper context -3. Recent context is perfect for session start -4. Combines both sessions and observations in one request -5. Use this when user asks "what did we do last time?" - -**Token Efficiency:** -- limit=3 sessions: ~1,500-2,500 tokens (includes observations) -- limit=5 sessions: ~2,500-4,000 tokens -- limit=10 sessions: ~5,000-8,000 tokens -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Recent Context - -**Use recent-context when:** -- Starting a new session -- User asks about recent work -- Need quick catch-up on project activity -- Want both sessions and observations together - -**Don't use recent-context when:** -- Looking for specific topics (use search instead) -- Need timeline around specific event (use timeline instead) -- Want only observations or only sessions (use search operations) - -## Comparison with Other Operations - -| Operation | Use Case | Token Cost | -|-----------|----------|------------| -| recent-context | Quick catch-up on recent work | 1,500-4,000 | -| sessions search | Find sessions by topic | 50-100 per result (index) | -| observations search | Find specific implementations | 50-100 per result (index) | -| timeline | Context around specific point | 3,000-6,000 | - -Recent context is optimized for "what happened recently?" questions with minimal token usage. diff --git a/plugin/skills/mem-search/operations/sessions.md b/plugin/skills/mem-search/operations/sessions.md deleted file mode 100644 index b69b4765..00000000 --- a/plugin/skills/mem-search/operations/sessions.md +++ /dev/null @@ -1,124 +0,0 @@ -# Search Sessions (Full-Text) - -Search session summaries using natural language queries. - -## When to Use - -- User asks: "What did we work on last week?" -- User asks: "What sessions involved database work?" -- User asks: "Show me sessions where we fixed bugs" -- Looking for past sessions by topic or theme - -## Command - -```bash -curl -s "http://localhost:37777/api/search/sessions?query=authentication&format=index&limit=5" -``` - -## Parameters - -- **query** (required): Search terms (e.g., "authentication", "database migration", "bug fixes") -- **format**: "index" (summary) or "full" (complete details). Default: "full" -- **limit**: Number of results (default: 20, max: 100) -- **project**: Filter by project name (optional) -- **dateStart/dateEnd**: Filter by date range (optional) - -## When to Use Each Format - -**Use format=index for:** -- Quick overviews of past sessions -- Finding session IDs for deeper investigation -- Listing multiple sessions -- **Token cost: ~50-100 per result** - -**Use format=full for:** -- Complete session summaries with requests, completions, learnings -- Understanding the full context of a session -- **Token cost: ~500-1000 per result** - -## Example Response (format=index) - -```json -{ - "query": "authentication", - "count": 3, - "format": "index", - "results": [ - { - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -## How to Present Results - -For format=index, present as a compact list: - -```markdown -Found 3 sessions about "authentication": - -šŸŽÆ **Session #545** Implemented JWT authentication system - > Added token-based auth with refresh tokens - > Nov 9, 2024 ā€¢ api-server - -šŸŽÆ **Session #546** Fixed authentication token expiration - > Resolved race condition in token refresh flow - > Nov 8, 2024 ā€¢ api-server -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Session Summary Structure - -Full session summaries include: - -- **Session request**: What the user asked for -- **What was completed**: Summary of work done -- **Key learnings**: Important insights and discoveries -- **Files modified**: List of changed files -- **Observations**: Links to detailed observations - -## Error Handling - -**Missing query parameter:** -```json -{"error": "Missing required parameter: query"} -``` -Fix: Add the query parameter - -**No results found:** -```json -{"query": "foobar", "count": 0, "results": []} -``` -Response: "No sessions found for 'foobar'. Try different search terms." - -## Tips - -1. Be specific: "JWT authentication implementation" > "auth" -2. Start with format=index and limit=5-10 -3. Use dateStart for recent sessions: `?query=auth&dateStart=2024-11-01` -4. Sessions provide high-level overview, observations provide details -5. Use project filtering when working on one codebase - -**Token Efficiency:** -- Start with format=index (~50-100 tokens per result) -- Use format=full only for relevant items (~500-1000 tokens per result) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Sessions vs Observations - -**Use sessions search when:** -- Looking for high-level work summaries -- Understanding what was done in past sessions -- Getting overview of recent activity - -**Use observations search when:** -- Looking for specific implementation details -- Finding bugs, features, or decisions -- Need fine-grained context about code changes diff --git a/plugin/skills/mem-search/operations/timeline-by-query.md b/plugin/skills/mem-search/operations/timeline-by-query.md deleted file mode 100644 index 050c76be..00000000 --- a/plugin/skills/mem-search/operations/timeline-by-query.md +++ /dev/null @@ -1,194 +0,0 @@ -# Timeline by Query - -Search for observations and get timeline context in a single request. Combines search + timeline into one operation. - -## When to Use - -- User asks: "What was happening when we worked on authentication?" -- User asks: "Show me context around bug fixes" -- User asks: "Timeline of database work" -- Need to find something then see temporal context - -## MCP Tool - -Use the `get_timeline_by_query` MCP tool: - -``` -# Auto mode: Uses top search result as timeline anchor -get_timeline_by_query(query="authentication", mode="auto", depth_before=10, depth_after=10) - -# Interactive mode: Shows top N search results for manual selection -get_timeline_by_query(query="authentication", mode="interactive", limit=5) -``` - -## Parameters - -- **query** (required): Search terms (e.g., "authentication", "bug fix", "database") -- **mode**: Search mode - - `auto` (default): Automatically uses top search result as timeline anchor - - `interactive`: Returns top N search results for manual anchor selection -- **depth_before**: Records before anchor (default: 10, max: 50) - for auto mode -- **depth_after**: Records after anchor (default: 10, max: 50) - for auto mode -- **limit**: Number of search results (default: 5, max: 20) - for interactive mode -- **project**: Filter by project name (optional) - -## Auto Mode (Recommended) - -Automatically gets timeline around best match: - -``` -get_timeline_by_query(query="JWT authentication", mode="auto", depth_before=10, depth_after=10) -``` - -**Response:** -```json -{ - "query": "JWT authentication", - "mode": "auto", - "best_match": { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "score": 0.95 - }, - "timeline": [ - // ... timeline records around observation #1234 - ] -} -``` - -**When to use auto mode:** -- You're confident the top result is what you want -- Want fastest path to timeline context -- Query is specific enough for accurate top result - -## Interactive Mode - -Shows top search results for manual review: - -``` -get_timeline_by_query(query="authentication", mode="interactive", limit=5) -``` - -**Response:** -```json -{ - "query": "authentication", - "mode": "interactive", - "top_matches": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "score": 0.95 - }, - { - "id": 1240, - "type": "bugfix", - "title": "Fixed authentication token expiration", - "subtitle": "Resolved race condition in refresh flow", - "score": 0.87 - } - ], - "next_step": "Use get_context_timeline(anchor=, depth_before=10, depth_after=10)" -} -``` - -**When to use interactive mode:** -- Query is broad and may have multiple relevant results -- Want to review options before getting timeline -- Not sure which result is most relevant - -## How to Present Results - -**For auto mode:** - -```markdown -## Timeline: JWT authentication - -**Best Match:** šŸŸ£ Observation #1234 - Implemented JWT authentication (score: 0.95) - -### Before (10 records) -**2:45 PM** - šŸŸ£ Added authentication middleware - -### ā­ Anchor Point (2:55 PM) -šŸŸ£ **Observation #1234**: Implemented JWT authentication - -### After (10 records) -**3:00 PM** - šŸŽÆ Session completed: JWT authentication system -``` - -**For interactive mode:** - -```markdown -Found 5 matches for "authentication": - -1. šŸŸ£ **#1234** Implemented JWT authentication (score: 0.95) - > Added token-based auth with refresh tokens - -2. šŸ”“ **#1240** Fixed authentication token expiration (score: 0.87) - > Resolved race condition in refresh flow - -To see timeline context, use observation ID with timeline operation. -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Error Handling - -**Missing query parameter:** -```json -{"error": "Missing required parameter: query"} -``` -Fix: Add the query parameter - -**No results found:** -```json -{"query": "foobar", "top_matches": []} -``` -Response: "No results found for 'foobar'. Try different search terms." - -## Tips - -1. **Use auto mode** for specific queries: "JWT authentication implementation" -2. **Use interactive mode** for broad queries: "authentication" -3. Start with depth 10/10 for balanced context -4. Be specific in queries for better auto mode accuracy -5. This is fastest way to find + explore context in one request - -**Token Efficiency:** -- Auto mode: ~3,000-4,000 tokens (search + timeline) -- Interactive mode: ~500-1,000 tokens (search results only) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## Workflow Comparison - -**timeline-by-query (auto):** -1. One request ā†’ get timeline around best match -2. ~3,000 tokens - -**timeline-by-query (interactive) ā†’ timeline:** -1. First request ā†’ see top matches (~500 tokens) -2. Second request ā†’ get timeline for chosen match (~3,000 tokens) -3. Total: ~3,500 tokens - -**observations search ā†’ timeline:** -1. Search observations (~500 tokens) -2. Get timeline for chosen result (~3,000 tokens) -3. Total: ~3,500 tokens - -Use auto mode when you're confident about the query. Use interactive mode or separate search when you want more control. - -## When to Use Timeline-by-Query - -**Use timeline-by-query when:** -- Need to find something AND see temporal context -- Want one-request convenience (auto mode) -- Investigating "what was happening when we worked on X?" -- Don't have observation ID already - -**Don't use timeline-by-query when:** -- Already have observation ID (use timeline instead) -- Just need search results (use observations search) -- Need recent work overview (use recent-context) diff --git a/plugin/skills/mem-search/operations/timeline.md b/plugin/skills/mem-search/operations/timeline.md deleted file mode 100644 index 5c2019d9..00000000 --- a/plugin/skills/mem-search/operations/timeline.md +++ /dev/null @@ -1,171 +0,0 @@ -# Get Context Timeline - -Get a chronological timeline of observations, sessions, and prompts around a specific point in time. - -## When to Use - -- User asks: "What was happening when we deployed?" -- User asks: "Show me context around that bug fix" -- User asks: "What happened before and after that change?" -- Need temporal context around an event - -## MCP Tool - -Use the `get_context_timeline` MCP tool: - -``` -get_context_timeline(anchor=1234, depth_before=10, depth_after=10) -get_context_timeline(anchor="S545", depth_before=10, depth_after=10) -get_context_timeline(anchor="2024-11-09T12:00:00Z", depth_before=10, depth_after=10) -``` - -## Parameters - -- **anchor** (required): Point in time to center timeline - - Observation ID: `1234` - - Session ID: `S545` - - ISO timestamp: `2024-11-09T12:00:00Z` -- **depth_before**: Number of records before anchor (default: 10, max: 50) -- **depth_after**: Number of records after anchor (default: 10, max: 50) -- **project**: Filter by project name (optional) - -## Response Structure - -Returns unified chronological timeline: - -```json -{ - "anchor": 1234, - "depth_before": 10, - "depth_after": 10, - "total_records": 21, - "timeline": [ - { - "record_type": "observation", - "id": 1230, - "type": "feature", - "title": "Added authentication middleware", - "created_at_epoch": 1699564700000 - }, - { - "record_type": "prompt", - "id": 1250, - "session_id": "S545", - "prompt_preview": "How do I add JWT authentication?", - "created_at_epoch": 1699564750000 - }, - { - "record_type": "observation", - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "created_at_epoch": 1699564800000, - "is_anchor": true - }, - { - "record_type": "session", - "id": 545, - "session_id": "S545", - "title": "Implemented JWT authentication system", - "created_at_epoch": 1699564900000 - } - ] -} -``` - -## How to Present Results - -Present as chronological narrative with anchor highlighted: - -```markdown -## Timeline around Observation #1234 - -### Before (10 records) - -**2:45 PM** - šŸŸ£ Observation #1230: Added authentication middleware - -**2:50 PM** - šŸ’¬ User asked: "How do I add JWT authentication?" - -### ā­ Anchor Point (2:55 PM) -šŸŸ£ **Observation #1234**: Implemented JWT authentication - -### After (10 records) - -**3:00 PM** - šŸŽÆ Session #545 completed: Implemented JWT authentication system - -**3:05 PM** - šŸ”“ Observation #1235: Fixed token expiration edge case -``` - -For complete formatting guidelines, see [formatting.md](formatting.md). - -## Anchor Types - -**Observation ID:** -- Use when you know the specific observation ID -- Example: `anchor=1234` - -**Session ID:** -- Use when you want context around a session -- Example: `anchor=S545` - -**ISO Timestamp:** -- Use when you know approximate time -- Example: `anchor=2024-11-09T14:30:00Z` - -## Error Handling - -**Missing anchor parameter:** -```json -{"error": "Missing required parameter: anchor"} -``` -Fix: Add the anchor parameter - -**Anchor not found:** -```json -{"error": "Anchor not found: 9999"} -``` -Response: "Observation #9999 not found. Check the ID or try a different anchor." - -**Invalid timestamp:** -```json -{"error": "Invalid timestamp format"} -``` -Fix: Use ISO 8601 format: `2024-11-09T14:30:00Z` - -## Tips - -1. Start with depth_before=10, depth_after=10 for balanced context -2. Increase depth for broader investigation (max: 50 each) -3. Use observation IDs from search results as anchors -4. Timelines show all record types interleaved chronologically -5. Perfect for understanding "what was happening when X occurred" - -**Token Efficiency:** -- depth 10/10: ~3,000-4,000 tokens (21 records) -- depth 20/20: ~6,000-8,000 tokens (41 records) -- depth 50/50: ~15,000-20,000 tokens (101 records) -- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md) - -## When to Use Timeline - -**Use timeline when:** -- Need context around specific event -- Understanding sequence of events -- Investigating "what was happening then?" -- Want all record types (observations, sessions, prompts) together - -**Don't use timeline when:** -- Just need recent work (use recent-context) -- Looking for specific topics (use search) -- Don't have an anchor point (use timeline-by-query) - -## Comparison with Timeline-by-Query - -| Feature | timeline | timeline-by-query | -|---------|----------|-------------------| -| Requires anchor | Yes (ID or timestamp) | No (uses search query) | -| Best for | Known event investigation | Finding then exploring context | -| Steps | 1 (direct timeline) | 2 (search + timeline) | -| Use when | You have observation ID | You have search term | - -Timeline is faster when you already know the anchor point. diff --git a/plugin/skills/mem-search/principles/.gitkeep b/plugin/skills/mem-search/principles/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/plugin/skills/mem-search/principles/anti-patterns.md b/plugin/skills/mem-search/principles/anti-patterns.md deleted file mode 100644 index acd3b1cd..00000000 --- a/plugin/skills/mem-search/principles/anti-patterns.md +++ /dev/null @@ -1,176 +0,0 @@ -# Anti-Pattern Catalogue - -Common mistakes to avoid when using the HTTP search API. These anti-patterns address LLM training biases and prevent token-wasting behaviors. - -## Anti-Pattern 1: Skipping Index Format - -**The Mistake:** -```bash -# āŒ Bad: Jump straight to full format -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=20" -``` - -**Why It's Wrong:** -- 20 Ɨ 750 tokens = 15,000 tokens -- May hit MCP token limits -- 99% wasted on irrelevant results - -**The Correction:** -```bash -# āœ… Good: Start with index, review, then request full selectively -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -# Review results, identify relevant items -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=1&offset=2" -``` - -**What It Teaches:** -Progressive disclosure isn't optional - it's essential for scale. - -**LLM Behavior Insight:** -LLMs trained on code examples may have seen `format=full` as "more complete" and default to it. - ---- - -## Anti-Pattern 2: Over-Requesting Results - -**The Mistake:** -```bash -# āŒ Bad: Request limit=20 without reviewing index first -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=20" -``` - -**Why It's Wrong:** -- Most of 20 results will be irrelevant -- Wastes tokens and time -- Overwhelms review process - -**The Correction:** -```bash -# āœ… Good: Start small, paginate if needed -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5" -# If needed, paginate: -curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5&offset=5" -``` - -**What It Teaches:** -Start small (limit=3-5), review, paginate if needed. - -**LLM Behavior Insight:** -LLMs may think "more results = more thorough" without considering relevance. - ---- - -## Anti-Pattern 3: Ignoring Tool Specialization - -**The Mistake:** -```bash -# āŒ Bad: Use generic search for everything -curl -s "http://localhost:37777/api/search/observations?query=bugfix&format=index&limit=10" -``` - -**Why It's Wrong:** -- Specialized tools (by-type, by-concept, by-file) are more efficient -- Generic search mixes all result types -- Misses filtering optimization - -**The Correction:** -```bash -# āœ… Good: Use specialized endpoint when applicable -curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=10" -``` - -**What It Teaches:** -The decision tree exists for a reason - follow it. - -**LLM Behavior Insight:** -LLMs may gravitate toward "general purpose" tools to avoid decision-making. - ---- - -## Anti-Pattern 4: Loading Full Context Prematurely - -**The Mistake:** -```bash -# āŒ Bad: Request full format before understanding what's relevant -curl -s "http://localhost:37777/api/search/observations?query=database&format=full&limit=10" -``` - -**Why It's Wrong:** -- Can't filter relevance without seeing index first -- Wastes tokens on irrelevant full details -- 10 Ɨ 750 = 7,500 tokens for potentially zero useful results - -**The Correction:** -```bash -# āœ… Good: Index first to identify relevance -curl -s "http://localhost:37777/api/search/observations?query=database&format=index&limit=10" -# Identify relevant: #1234 and #1250 -curl -s "http://localhost:37777/api/search/observations?query=database+1234&format=full&limit=1" -curl -s "http://localhost:37777/api/search/observations?query=database+1250&format=full&limit=1" -``` - -**What It Teaches:** -Filtering is a prerequisite for expansion. - -**LLM Behavior Insight:** -LLMs may try to "get everything at once" to avoid multiple tool calls. - ---- - -## Anti-Pattern 5: Not Using Timeline Tools - -**The Mistake:** -```bash -# āŒ Bad: Search for individual observations separately -curl -s "http://localhost:37777/api/search/observations?query=before+deployment" -curl -s "http://localhost:37777/api/search/observations?query=during+deployment" -curl -s "http://localhost:37777/api/search/observations?query=after+deployment" -``` - -**Why It's Wrong:** -- Misses context around events -- Inefficient (N searches vs 1 timeline) -- Temporal relationships lost - -**The Correction:** -```bash -# āœ… Good: Use timeline tool for contextual investigation -curl -s "http://localhost:37777/api/timeline/by-query?query=deployment&depth_before=10&depth_after=10" -``` - -**What It Teaches:** -Tool composition - some tools are designed to work together. - -**LLM Behavior Insight:** -LLMs may not naturally discover tool composition patterns. - ---- - -## Why These Anti-Patterns Matter - -**Addresses LLM Training Bias:** -LLMs default to "load everything" behavior from web scraping training data where thoroughness was rewarded. - -**Teaches Protocol Awareness:** -HTTP APIs and MCP have real token limits that can break the system. - -**Prevents User Frustration:** -Token limit errors confuse users and break workflows. - -**Builds Good Habits:** -Anti-patterns teach the "why" behind best practices. - -**Makes Implicit Explicit:** -Surfaces mental models that experienced users internalize but novices miss. - ---- - -## What Happens If These Are Ignored - -- **No progressive disclosure**: Every search loads limit=20 in full format ā†’ token exhaustion -- **Over-requesting**: 15,000 token searches for 2 relevant results -- **Wrong tool**: Generic search when specialized filters would be 10x faster -- **Premature expansion**: Load full details before knowing relevance -- **Missing composition**: Single-tool thinking, missing powerful multi-step workflows - -**Bottom Line:** These anti-patterns waste 5-10x more tokens than necessary and frequently cause system failures. diff --git a/plugin/skills/mem-search/principles/progressive-disclosure.md b/plugin/skills/mem-search/principles/progressive-disclosure.md deleted file mode 100644 index 7fcfa968..00000000 --- a/plugin/skills/mem-search/principles/progressive-disclosure.md +++ /dev/null @@ -1,120 +0,0 @@ -# Progressive Disclosure Pattern (MANDATORY) - -**Core Principle**: Find the smallest set of high-signal tokens first (index format), then drill down to full details only for relevant items. - -## The 4-Step Workflow - -### Step 1: Start with Index Format - -**Action:** -- Use `format=index` (default in most operations) -- Set `limit=3-5` (not 20) -- Review titles and dates ONLY - -**Token Cost:** ~50-100 tokens per result - -**Why:** Minimal token investment for maximum signal. Get overview before committing to full details. - -**Example:** -```bash -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5" -``` - -**Response:** -```json -{ - "query": "authentication", - "count": 5, - "format": "index", - "results": [ - { - "id": 1234, - "type": "feature", - "title": "Implemented JWT authentication", - "subtitle": "Added token-based auth with refresh tokens", - "created_at_epoch": 1699564800000, - "project": "api-server" - } - ] -} -``` - -### Step 2: Identify Relevant Items - -**Cognitive Task:** -- Scan index results for relevance -- Note which items need full details -- Discard irrelevant items - -**Why:** Human-in-the-loop filtering before expensive operations. Don't load full details for items you'll ignore. - -### Step 3: Request Full Details (Selectively) - -**Action:** -- Use `format=full` ONLY for specific items of interest -- Target by ID or use refined search query - -**Token Cost:** ~500-1000 tokens per result - -**Principle:** Load only what you need - -**Example:** -```bash -# After reviewing index, get full details for observation #1234 -curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=1&offset=2" -``` - -**Why:** Targeted token expenditure with high ROI. 10x cost difference means selectivity matters. - -### Step 4: Refine with Filters (If Needed) - -**Techniques:** -- Use `type`, `dateStart`/`dateEnd`, `concepts`, `files` filters -- Narrow scope BEFORE requesting more results -- Use `offset` for pagination instead of large limits - -**Why:** Reduce result set first, then expand selectively. Don't load 20 results when filters could narrow to 3. - -## Token Budget Awareness - -**Costs:** -- Index result: ~50-100 tokens -- Full result: ~500-1000 tokens -- 10x cost difference - -**Starting Points:** -- Start with `limit=3-5` (not 20) -- Reduce limit if hitting token errors - -**Savings Example:** -- Naive: 10 items Ɨ 750 tokens (avg full) = 7,500 tokens -- Progressive: (5 items Ɨ 75 tokens index) + (2 items Ɨ 750 tokens full) = 1,875 tokens -- **Savings: 5,625 tokens (75% reduction)** - -## What Problems This Solves - -1. **Token exhaustion**: Without this, LLMs load everything in full format (9,000+ tokens for 10 items) -2. **Poor signal-to-noise**: Loading full details for irrelevant items wastes tokens -3. **MCP limits**: Large payloads hit protocol limits (system failures) -4. **Inefficiency**: Loading 20 full results when only 2 are relevant - -## How It Scales - -**With 10 records:** -- Index (500 tokens) ā†’ Full (2,000 tokens for 2 relevant) = 2,500 tokens -- Without pattern: Full (10,000 tokens for all 10) = 4x more expensive - -**With 1,000 records:** -- Index (500 tokens for top 5) ā†’ Full (1,000 tokens for 1 relevant) = 1,500 tokens -- Without pattern: Would hit MCP limits before seeing relevant data - -## Context Engineering Alignment - -This pattern implements core context engineering principles: - -- **Just-in-time context**: Load data dynamically at runtime -- **Progressive disclosure**: Lightweight identifiers (index) ā†’ full details as needed -- **Token efficiency**: Minimal high-signal tokens first, expand selectively -- **Attention budget**: Treat context as finite resource with diminishing returns - -Always start with the smallest set of high-signal tokens that maximize likelihood of desired outcome. diff --git a/scripts/build-hooks.js b/scripts/build-hooks.js index 6c594cb8..0cbc3071 100644 --- a/scripts/build-hooks.js +++ b/scripts/build-hooks.js @@ -191,28 +191,11 @@ async function buildHooks() { console.log(`āœ“ ${hook.name} built (${sizeInKB} KB)`); } - // Build mem-search skill zip for Claude Desktop - console.log('\nšŸ“¦ Building mem-search skill zip for Claude Desktop...'); - const { execSync } = await import('child_process'); - const zipOutput = 'plugin/skills/mem-search.zip'; - - // Remove old zip if exists - if (fs.existsSync(zipOutput)) { - fs.unlinkSync(zipOutput); - } - - // Create zip from mem-search skill directory - execSync(`cd plugin/skills && zip -r mem-search.zip mem-search/`, { stdio: 'pipe' }); - const zipStats = fs.statSync(zipOutput); - console.log(`āœ“ mem-search.zip built (${(zipStats.size / 1024).toFixed(2)} KB)`); - console.log('\nāœ… All hooks, worker service, and MCP server built successfully!'); console.log(` Output: ${hooksDir}/`); console.log(` - Hooks: *-hook.js`); console.log(` - Worker: worker-service.cjs`); console.log(` - MCP Server: mcp-server.cjs`); - console.log(` - Skills: plugin/skills/`); - console.log(` - Desktop Skill: plugin/skills/mem-search.zip`); console.log('\nšŸ’” Note: Dependencies will be auto-installed on first hook execution'); } catch (error) { diff --git a/src/servers/mcp-server.ts b/src/servers/mcp-server.ts index a1ec67b4..7035af70 100644 --- a/src/servers/mcp-server.ts +++ b/src/servers/mcp-server.ts @@ -185,7 +185,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'search', - description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd', + description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy', inputSchema: { type: 'object', properties: {}, @@ -198,7 +198,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'timeline', - description: 'Step 2: Get context around results. Params: anchor (observation ID), depth_before, depth_after, project', + description: 'Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project', inputSchema: { type: 'object', properties: {}, @@ -211,7 +211,7 @@ NEVER fetch full details without filtering first. 10x token savings.`, }, { name: 'get_observations', - description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs), project', + description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project', inputSchema: { type: 'object', properties: {