memax-cli 0.1.0-alpha.17 → 0.1.0-alpha.1890

package/assets/skills/memax-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memax-memory
-description: Persistent memory layer using Memax. Gives Claude the ability to recall past context and store new learnings across sessions via the Memax MCP tools (memax_recall, memax_push, memax_get, memax_search, memax_forget). Use this skill at the START of every conversation to do a light context check, and throughout the session whenever the user references past decisions, project context, architecture, or conventions — or whenever Claude discovers something worth remembering for future sessions. Also trigger when the user explicitly asks to remember or forget something, or when working on a project where prior context would prevent redundant questions. If Memax MCP tools are available, this skill applies.
+description: Persistent memory layer using Memax. Gives Claude the ability to recall past context and store new learnings across sessions via the Memax MCP tools (memax_recall, memax_push, memax_get, memax_list, memax_forget, memax_capture, memax_topics, memax_hubs, memax_hub_members). Use this skill at the START of every conversation to do a light context check, and throughout the session whenever the user references past decisions, project context, architecture, or conventions — or whenever Claude discovers something worth remembering for future sessions. Also trigger when the user explicitly asks to remember or forget something, or when working on a project where prior context would prevent redundant questions. If Memax MCP tools are available, this skill applies.
 ---
 
 # Memax Memory — Persistent Context for Claude
@@ -11,14 +11,17 @@ Your job is to use it proactively. Don't wait for the user to say "check Memax"
 
 ## Tools
 
-| Tool            | Purpose                                               |
-| --------------- | ----------------------------------------------------- |
-| `memax_recall`  | Semantic search — find memories relevant to a query   |
-| `memax_push`    | Save a new memory                                     |
-| `memax_get`     | Read the full content of a specific memory by ID      |
-| `memax_search`  | Browse/list memories by category                      |
-| `memax_forget`  | Delete a memory by ID                                 |
-| `memax_capture` | Extract and save key decisions from a session summary |
+| Tool                | Purpose                                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memax_recall`      | Semantic search — find memories relevant to a natural language query across all accessible hubs                                                   |
+| `memax_push`        | Save a new memory — supports `hub_id` to target a specific hub, `hub_reason` (required for team hubs), and automatic classification for retrieval |
+| `memax_get`         | Read the full content of a specific memory by ID                                                                                                  |
+| `memax_list`        | Browse/list memories with pagination and sorting                                                                                                  |
+| `memax_forget`      | Delete a memory by ID                                                                                                                             |
+| `memax_capture`     | Extract and save key decisions, learnings from a session summary                                                                                  |
+| `memax_topics`      | Browse the topic tree, or list memories within a specific topic                                                                                   |
+| `memax_hubs`        | List hubs the user can access (IDs, slugs, roles, memory counts)                                                                                  |
+| `memax_hub_members` | List members of a specific hub                                                                                                                    |
 
 ## When to recall (read)
 
@@ -39,7 +42,7 @@ Go deeper when you notice:
 - Architecture or convention questions: "how do we handle X," "what's our pattern for Y"
 - The user correcting you on something that suggests prior context exists
 
-For deeper recall, chain multiple calls: `memax_recall` to find relevant memories, then `memax_get` on specific IDs to read full details, or `memax_search` to browse a category.
+For deeper recall, chain multiple calls: `memax_recall` to find relevant memories, then `memax_get` on specific IDs to read full details, `memax_list` to browse recent memories, or `memax_topics` to explore the user's knowledge tree and find memories organized by topic.
 
 ### Don't over-recall
 
@@ -85,10 +88,10 @@ Include the _why_ behind decisions — rationale is the most valuable thing to r
 
 ### Push cadence
 
-- Push as soon as something important is decided or discovered — don't batch
+- Push when you reach a durable decision, solve a non-obvious problem, or learn something worth keeping across sessions
 - If a conversation is heavy on decisions (e.g., architecture planning), you might push 3-5 memories
 - For a routine task, zero pushes is fine — not every session produces lasting knowledge
-- When in doubt, push it. A slightly redundant memory is better than a lost insight. Memax handles merging and deduplication on the server side, so don't worry about conflicts or overlap with existing memories.
+- Routine progress and mid-task notes don't need to be pushed — save the signal, skip the noise. Memax handles deduplication on the server side, so don't worry about overlap with existing memories.
 
 ## Handling outdated information
 
@@ -96,22 +99,34 @@ If you recall a memory that looks outdated or contradicts what you're learning i
 
 The exception: if the user explicitly asks you to delete something ("forget that we use Redis" or "remove the old deployment notes"), use `memax_forget` to honor the request.
 
-## Categories
+## Classification
 
-Memax organizes memories into categories. Use them when pushing to keep things browsable:
+Memax classifies memories automatically using invisible retrieval axes. Do not pass taxonomy labels when pushing. Instead, write clear, self-contained content and use `hint` when extra context would help the server understand the memory.
 
-| Category    | What goes here                                         | Example                                      |
-| ----------- | ------------------------------------------------------ | -------------------------------------------- |
-| `core`      | Fundamental architecture, tech stack, core patterns    | "API uses stdlib net/http, not Gin"          |
-| `process`   | Workflows, deployment steps, development practices     | "Deploy to Fly.io requires fly.toml rename"  |
-| `decisions` | Key choices with rationale (ADR-style)                 | "Chose River over BullMQ because..."         |
-| `reference` | Useful lookup info, configurations, external resources | "Neon connection pooling limit: 100"         |
-| `daily`     | Working notes, debugging sessions, ephemeral context   | "Auth timeout was caused by Neon cold start" |
-| `personal`  | User preferences, coding style, workflow habits        | "User prefers terse responses, no summaries" |
+Good hints are short and plain-language:
 
-When pushing, set the category if you know it. If unsure, omit it — the server auto-classifies via LLM.
+- "Architecture decision from today's auth review"
+- "Runbook for staging deploy recovery"
+- "Personal preference about code review style"
 
-When searching, `memax_recall` does semantic search across all categories, so you don't need to filter by category when reading — just when writing.
+Use topics, tags, pins, and explicit forget/delete actions for user-facing organization and corrections. Retrieval searches across every hub the token can access, with active hub context used as a ranking boost rather than a hard boundary.
+
+## Topics
+
+Memax automatically organizes memories into a topic tree based on content. Use `memax_topics` to:
+
+- **Browse the full tree** (no arguments) — returns all topics with memory counts, useful for understanding what the user's knowledge base covers
+- **Drill into a topic** (pass `topic_id`) — returns the memories within that topic
+
+Topics are great for structured exploration: "what do I know about deployment?" → browse topics → drill into the relevant one. This complements `memax_recall` (semantic search) with a more navigable, hierarchical view.
+
+## Hubs
+
+Users can have multiple hubs — a personal hub and shared team hubs. Use `memax_hubs` to list what's available. When pushing memories, you can optionally target a specific hub with `hub_id` and provide `hub_reason` to explain why the memory belongs there.
+
+- `memax_recall` searches across **all accessible hubs** by default — no need to specify a hub for reading
+- `memax_push` without `hub_id` saves to the user's personal hub
+- `memax_hub_members` shows who has access to a given hub — useful when the user asks about team knowledge or shared context
 
 ## Behavior across environments
 
@@ -146,9 +161,13 @@ Don't push a "session summary" — push the individual insights that would be us
 ## Quick reference
 
 ```
-Session start   →  memax_recall(topic from first message)
-Cue detected    →  memax_recall(specific query) → memax_get(id) if needed
-Important info  →  memax_push(clear, self-contained summary with rationale)
-User says forget → memax_forget(id)
-Outdated memory →  Just push the new version, Memax handles merging
+Session start    →  memax_recall(topic from first message)
+Cue detected     →  memax_recall(specific query) → memax_get(id) if needed
+Browse structure →  memax_topics() → memax_topics(topic_id) to drill in
+Browse recent     →  memax_list(limit, cursor) with pagination
+Check hubs       →  memax_hubs() → memax_hub_members(hub_id)
+Important info   →  memax_push(clear, self-contained summary with rationale)
+Team knowledge   →  memax_push(content, hub_id, hub_reason) to target a shared hub
+User says forget →  memax_forget(id)
+Outdated memory  →  Just push the new version, Memax handles merging
 ```

package/dist/commands/agent-configs.d.ts

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { type ProjectScope } from "../lib/project-context.js";
+import type { Scope } from "memax-sdk";
+export declare function syncAgentMemoryCommand(options?: SyncAgentOptions): Promise<void>;
+export declare function listAgentConfigsCommand(): Promise<void>;
+export declare function listDeletedAgentConfigsCommand(): Promise<void>;
+export declare function restoreDeletedAgentConfigsCommand(): Promise<void>;
+interface AgentConfigPlacement {
+    kind: "present" | "restorable" | "different_project" | "unresolved";
+    path?: string;
+    reason: string;
+}
+interface ClassifyAgentConfigPlacementOptions extends ResolveAgentConfigWritePathOptions {
+    localByKey?: Map<string, AgentConfigLocation>;
+}
+export declare function classifyAgentConfigPlacement(agent: string, filePath: string, scope: Scope, options?: ClassifyAgentConfigPlacementOptions): AgentConfigPlacement;
+export declare function doctorAgentConfigsCommand(): Promise<void>;
+export declare function registerAgentConfigCommands(agentsCmd: Command): void;
+export declare function deleteAgentConfigsCommand(): Promise<void>;
+interface AgentConfigLocation {
+    agent: string;
+    label: string;
+    path: string;
+    filePath: string;
+    scope: Scope;
+}
+interface ResolveAgentConfigWritePathOptions {
+    cwd?: string;
+    home?: string;
+    currentProjectScope?: ProjectScope;
+    findClaudeProjectDir?: (scope: Scope) => string | null;
+}
+export declare function resolveAgentConfigWritePath(agent: string, filePath: string, scope: Scope, options?: ResolveAgentConfigWritePathOptions): string | null;
+interface SyncAgentOptions {
+    push?: boolean;
+    pull?: boolean;
+    /** Skip conflicts silently (used by setup — conflicts can be resolved later via `memax agents sync`). */
+    skipConflicts?: boolean;
+}
+export {};
+//# sourceMappingURL=agent-configs.d.ts.map

package/dist/commands/agent-configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-configs.d.ts","sourceRoot":"","sources":["../../src/commands/agent-configs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,OAAO,EAOL,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAe,KAAK,EAAkB,MAAM,WAAW,CAAC;AAEpE,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwD7D;AAED,wBAAsB,8BAA8B,IAAI,OAAO,CAAC,IAAI,CAAC,CAkCpE;AAED,wBAAsB,iCAAiC,IAAI,OAAO,CAAC,IAAI,CAAC,CAgHvE;AAED,UAAU,oBAAoB;IAC5B,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,mBAAmB,GAAG,YAAY,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,mCAAoC,SAAQ,kCAAkC;IACtF,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC/C;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,mCAAwC,GAChD,oBAAoB,CAkCtB;AAED,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiK/D;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAsCpE;AAED,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsP/D;AAcD,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,UAAU,kCAAkC;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,YAAY,CAAC;IACnC,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,IAAI,CAAC;CACxD;AAiDD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,kCAAuC,GAC/C,MAAM,GAAG,IAAI,CA4Gf;AAkQD,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yGAAyG;IACzG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}