{"_id":"@adhd/sox-extension-memory-usage","_rev":"3-8b1d11886a47bbe58713d87f907000b6","name":"@adhd/sox-extension-memory-usage","dist-tags":{"latest":"0.2.2"},"versions":{"0.2.0":{"name":"@adhd/sox-extension-memory-usage","version":"0.2.0","license":"MIT","_id":"@adhd/sox-extension-memory-usage@0.2.0","maintainers":[{"name":"pseudosky","email":"skywinston.sk@gmail.com"}],"dist":{"shasum":"df4934e6f836dcb9a3cd307ae06ed0aced6f8575","tarball":"https://registry.npmjs.org/@adhd/sox-extension-memory-usage/-/sox-extension-memory-usage-0.2.0.tgz","fileCount":5,"integrity":"sha512-GJgT1ZVvt3AN7y15RHKOghZ6z5TIUYUFSIKGg5lqxeBdS0xBj1dvruBnnzS4/EHBsKpqXR65+l0GOjFszODy8A==","signatures":[{"sig":"MEUCIQCraSmLabDGUkcHsphpd3D3WzswmUyb/2YxS4YinG8LSgIgVAbfTLdJr9hTh/4XCXepuoBXqFxFyFS39piGFHNLMzs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12056},"_from":"file:adhd-sox-extension-memory-usage-0.2.0.tgz","engines":{"node":">=20"},"_npmUser":{"name":"pseudosky","email":"skywinston.sk@gmail.com"},"_resolved":"/private/var/folders/yg/cfczgtx54bzfh74lx2_mv0z80000gp/T/286a17532a3b409f6170ffb0b146afc4/adhd-sox-extension-memory-usage-0.2.0.tgz","_integrity":"sha512-GJgT1ZVvt3AN7y15RHKOghZ6z5TIUYUFSIKGg5lqxeBdS0xBj1dvruBnnzS4/EHBsKpqXR65+l0GOjFszODy8A==","_npmVersion":"11.6.2","description":"memory-usage extension","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sox-extension-memory-usage_0.2.0_1782451181861_0.2935052061525756","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@adhd/sox-extension-memory-usage","version":"0.2.1","keywords":["memory","skill","mcp","typescript"],"license":"MIT","_id":"@adhd/sox-extension-memory-usage@0.2.1","maintainers":[{"name":"pseudosky","email":"skywinston.sk@gmail.com"}],"homepage":"https://github.com/PseudoSky/adhd","bugs":{"url":"https://github.com/PseudoSky/adhd/issues"},"dist":{"shasum":"d33f422d785a9bd2f984207103edeaf997dabe3f","tarball":"https://registry.npmjs.org/@adhd/sox-extension-memory-usage/-/sox-extension-memory-usage-0.2.1.tgz","fileCount":6,"integrity":"sha512-4tKpHaaI5Rtfvd99tFfzJxn8/XT7B6Jqq31E1ktrfvnPKOtJHIim2NScdq8a4rSfZqChl8DJ4VnQMWo0hEDuxQ==","signatures":[{"sig":"MEUCIQDbsv/fgcUGG6yLIx7NZnfZ1Lt7r1gOBhE/PcYRID0i1QIgZPtcrBi0w+qMVmIiQ9ckmJ4+8aDkkNZA9IGe2q1TIU0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30481},"_from":"file:adhd-sox-extension-memory-usage-0.2.1.tgz","engines":{"node":">=20"},"_npmUser":{"name":"pseudosky","email":"skywinston.sk@gmail.com"},"_resolved":"/private/var/folders/yg/cfczgtx54bzfh74lx2_mv0z80000gp/T/53d21cf009aae036f5560b29fcca3881/adhd-sox-extension-memory-usage-0.2.1.tgz","_integrity":"sha512-4tKpHaaI5Rtfvd99tFfzJxn8/XT7B6Jqq31E1ktrfvnPKOtJHIim2NScdq8a4rSfZqChl8DJ4VnQMWo0hEDuxQ==","repository":{"url":"git+https://github.com/PseudoSky/adhd.git","type":"git"},"_npmVersion":"11.6.2","description":"memory-usage extension","directories":{},"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sox-extension-memory-usage_0.2.1_1788566479719_0.6358175879247265","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"_id":"@adhd/sox-extension-memory-usage@0.2.2","bugs":{"url":"https://github.com/PseudoSky/adhd/issues"},"dist":{"shasum":"e5f6915a92c63f7e738ce09c9f27281595fc042c","tarball":"https://registry.npmjs.org/@adhd/sox-extension-memory-usage/-/sox-extension-memory-usage-0.2.2.tgz","fileCount":6,"integrity":"sha512-9xRXwBtFulSXBz1ogx+QeXB4QQF8ZXQ2CDSOMHsMVNBuna1UDEJPbQZeoQTXJ106NSpMRLW7zFN4YAWUOjU/HQ==","signatures":[{"sig":"MEUCIQDlIec4Rha/FBghcHAu7M91UJb/z+JnnLS+I7FDuOxSzQIgeXDC9C9MbYCav/iLZCja3puMwPMqYA/qtNltWx7Lt7A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDvcuuQfzFn0mJH4CRfCU4VZ7Ges6w3thCT/5i+UULWfAIhAPz1tKw4XpmaSti84YspjaEukZfwRw8aJV3Ep+shfmsg"}],"unpackedSize":31998},"name":"@adhd/sox-extension-memory-usage","_from":"file:adhd-sox-extension-memory-usage-0.2.2.tgz","engines":{"node":">=20"},"license":"MIT","version":"0.2.2","_npmUser":{"name":"pseudosky","email":"skywinston.sk@gmail.com"},"homepage":"https://github.com/PseudoSky/adhd","keywords":["memory","skill","mcp","typescript"],"_resolved":"/private/var/folders/yg/cfczgtx54bzfh74lx2_mv0z80000gp/T/4c3fbac6c79c4c4900934f691d15fc5a/adhd-sox-extension-memory-usage-0.2.2.tgz","_integrity":"sha512-9xRXwBtFulSXBz1ogx+QeXB4QQF8ZXQ2CDSOMHsMVNBuna1UDEJPbQZeoQTXJ106NSpMRLW7zFN4YAWUOjU/HQ==","repository":{"url":"git+https://github.com/PseudoSky/adhd.git","type":"git"},"_npmVersion":"11.6.2","description":"memory-usage extension","directories":{},"maintainers":[{"name":"pseudosky","email":"skywinston.sk@gmail.com"}],"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sox-extension-memory-usage_0.2.2_1790727227689_0.16249203805473988"}}},"time":{"created":"2026-06-26T05:19:41.694Z","modified":"2026-09-30T00:13:47.998Z","0.2.0":"2026-06-26T05:19:41.997Z","0.2.1":"2026-09-05T00:01:19.861Z","0.2.2":"2026-09-30T00:13:47.798Z"},"bugs":{"url":"https://github.com/PseudoSky/adhd/issues"},"license":"MIT","homepage":"https://github.com/PseudoSky/adhd","keywords":["memory","skill","mcp","typescript"],"repository":{"url":"git+https://github.com/PseudoSky/adhd.git","type":"git"},"description":"memory-usage extension","maintainers":[{"name":"pseudosky","email":"skywinston.sk@gmail.com"}],"readme":"# memory-usage\n\n> A declarative skill teaching an agent to recall prior knowledge before researching, and to write durable findings for the next agent — via the `memory_*` MCP tools.\n\n## Overview\n\n`@adhd/sox-extension-memory-usage` is a `type: skill` extension: the host reads its `SKILL.md` and injects the guidance below at invocation time — there is no code to run. It teaches an agent the everyday recall / write / update path against the sox-memory graph store served by `memory-server`, a sibling member of `sox-memory-bundle`. The store is a local, bi-temporal knowledge graph with hybrid (vector + full-text + temporal) recall; embeddings are local, so recall is offline and makes no network calls.\n\n```bash\npnpm add @adhd/sox-extension-memory-usage\n```\n\n## Install\n\n```bash\nsoxe install memory-usage\n```\n\nThe host injects this skill when an agent is about to research, decide, or answer (recall first), and when it produces a durable, sourced finding worth carrying forward (write it). It is not for transient chatter, project-secret values, or unsourced claims — and project-specific notes that name a repo/path/person belong in that project's own files, not the shared graph memory.\n\n## Recall before researching\n\n`query` is optional — omit it for an importance-ranked listing instead of a semantic search. Always pass a generous `token_budget` (the tool default is small; the assembler stops adding results once the budget is spent, so a default-budget recall can return far fewer results than `limit` allows):\n\n```jsonc\nmemory_recall({\n  query: \"how should an orchestrator decide a plan state is complete\",\n  token_budget: 50000,\n  limit: 8,\n  filters: {                          // all optional; exactly these eight keys are recognised\n    topic: \"execution-context-partition\",\n    tags: [\"orchestration\"],          // any-match by default; tags_match_all:true for all\n    project_path: \"/Users/you/repo\",  // or { prefix: \"/Users/you/\" }\n    importance_min: 3,\n    t_created_after: \"2026-01-01T00:00:00Z\",\n    t_created_before: \"2026-06-01T00:00:00Z\",\n    kinds: [\"episode\"]                 // node kinds to include — see below, defaults to [\"episode\"] even when filters is omitted entirely\n  }\n})\n```\n\nThe eight `filters` keys: `project_path`, `topic`, `tags`, `tags_match_all`, `importance_min`, `t_created_after`, `t_created_before`, and `kinds`.\n\n**`kinds` is not cosmetic — it decides what shows up at all.** The graph stores several node kinds besides `episode`: `entity`, `community`, and `session` nodes exist for clustering and graph traversal, and carry no readable `content` — recall renders them as `[entity] <uid>: ` with nothing after the colon. Regardless of whether `filters` is passed at all, `memory_recall` defaults `kinds` to `[\"episode\"]`, so those content-less nodes are excluded from ordinary recall automatically. Pass `filters: { kinds: [\"episode\", \"entity\"] }` (or any other combination) only when you deliberately want to see them — e.g. while inspecting the entity graph itself, not while recalling findings. Don't confuse this with the `kind:`/`audience:` tag-prefix convention below — that's an unrelated, purely tag-level organizing scheme for episodes.\n\n`agent_id` is a **top-level** parameter, never a `filters` key — pass it to hard-scope recall to episodes written by that agent. It only applies on the query path: omit `query` for the importance-ranked listing and `agent_id` is not applied.\n\nBefore filtering on a `topic`/`project_path`/tag value you're not sure exists, call `memory_topics`, `memory_list_projects`, or `memory_list_entities` to see what's actually in the store — a filter on a value nothing carries returns nothing.\n\n## Write durable findings\n\n`project_path` is **required** — pass the calling agent's actual workspace root explicitly, every time. There is no cwd/env/git fallback: an omitted or empty value fails the call outright with `{ code: \"E_MISSING_PROJECT_PATH\" }` before anything is written, and a wrong guess can't be fixed by rewriting (the dedup key ignores `project_path`) — only `memory_update` can correct it in place. There is no `scope` parameter on `memory_write`; a write lands in whichever store `db_path` selects (default: the shared user-scope store) — don't pass `scope` here, it only exists on `memory_recall` as a cosmetic label.\n\n```jsonc\nmemory_write({\n  content: \"<the finding — one focused idea>\",\n  project_path: \"/Users/you/repo\",   // REQUIRED — your actual workspace root, never inferred\n  topic: \"<topic>\",                  // drives organization + filtered recall\n  tags: [\"<concept>\"],               // also creates linkable entity nodes\n  name: \"<title>\",                   // optional episode title\n  summary: \"<1-3 sentences>\",        // optional; an extractive summary is generated if omitted\n  source: \"document\",                // message | tool_output | observation | document | reflection | import\n  agent_id: \"<your-agent-name>\",\n  importance: 7,                     // optional, 1-10\n  metadata: { original_path: \"<source path if any>\" }\n})\n```\n\n`memory_write_batch` enforces the same rule per item — any item missing `project_path` rejects the whole batch before any of it is written.\n\n**Chunk large content.** Write one focused idea per node, not a whole document — a multi-section doc as one node embeds only its first ~512 tokens (the rest is unsearchable) and crowds recall. `memory_write`'s `chunk_size` (default 500 tokens) splits oversized content at sentence boundaries into separate episodes linked back to the parent by a `DERIVED_FROM` edge — or split manually into a short summary node plus per-section nodes yourself.\n\n### `kind:`/`audience:` — tag-prefix conventions, not fields\n\nLifecycle and audience axes are plain tag prefixes recalled through `tags`, not dedicated fields:\n\n```jsonc\n// write — mark the intended reader and lifecycle kind\nmemory_write({\n  content: \"Orchestrators: dispatch.json depends_on must declare a dep for any shared file.\",\n  project_path: \"/Users/you/repo\",\n  tags: [\"audience:orchestrator\", \"kind:pattern\"],\n  source: \"observation\", agent_id: \"flash-impl\"\n})\n\n// recall — pull everything addressed to orchestrators\nmemory_recall({\n  query: \"parallel dispatch file-conflict safety\",\n  filters: { tags: [\"audience:orchestrator\"] },\n  token_budget: 50000, limit: 8\n})\n```\n\n## Edit or correct a finding\n\n`memory_update` edits an existing node in place — the `uid` is the required selector and is immutable. Changing `content` or `summary` re-embeds automatically; `metadata` deep-merges by default:\n\n```jsonc\nmemory_update({\n  uid: \"<episode_uid>\",\n  metadata: { reviewed_by: \"code-reviewer\" },  // deep-merged into node.meta\n  importance: 8                                 // and/or content/summary/name/topic/tags/t_occurred\n})\n```\n\nTo correct a *fact* rather than a node, prefer supersession: `memory_write` the replacement episode, then `memory_invalidate` the old one with a `replacement_uid` pointing at the new episode's uid — the old claim stays visible under `as_of` point-in-time recall but drops from current recall.\n\n## Other tools\n\n- **Discover valid filter values:** `memory_topics`, `memory_list_projects`, `memory_list_entities`, `memory_search_entities`.\n- **Graph traversal:** `memory_related` (neighbours), `memory_entity_episodes` (episodes mentioning an entity), `memory_get_community` (a cluster + members), `memory_supersession_chain`, `memory_near_duplicates`.\n- **Curate:** `memory_curate` with an `op` of `retag`, `set_topic`, `set_importance`, `merge_duplicates`, or `recluster` (which returns a durable job handle; poll it with `op: \"recluster_status\"`). To edit a live node in place, `memory_update`.\n- **Claims (SR-7):** `memory_claim_upsert` (atomic claim/update for a caller), `memory_claim_get`, `memory_claim_list`.\n- **Session state:** `memory_get_session_state` / `memory_save_session_state`.\n- **Health:** `memory_stats` (coverage + cluster quality), `memory_ping` (liveness), `memory_link` (create an edge between two existing nodes).\n\n`memory-server`'s own README documents the full input/output schema for all 23 tools.\n\n## Output shapes\n\n`memory_recall` returns ranked results, each with `uid`, `content`, `score`, `provenance` (which of `vec`/`fts`/`temporal` matched), `agent_id`, `content_hash`, plus `summary`, `topic`, `tags`, `project_path`, `importance`, `is_superseded`, `supersedes_uid`, and `community_uid`. `memory_write` returns `{ episode_uid, enrichment: { topic, project_path, project_path_source, summary, tags, near_dup } }` (`project_path_source` is `\"explicit\"` for a caller-supplied value), or `{ code: \"E_DEDUP\", existing_uid }` for a content-hash duplicate — writes are idempotent by content hash. `near_dup` is always `null` in that immediate response; near-duplicate detection is asynchronous — call `memory_near_duplicates` afterward to check whether a `SAME_AS` edge landed. `memory_update` returns `{ uid, updated_fields, reembedded }`.\n\n## Gotchas\n\n- **Writes are async-embedded.** The embedding lands *after* `memory_write` returns: a fresh episode is keyword/temporal-recallable immediately but vector-recallable only once the async embed completes (typically well under a second). A purely semantic recall fired right after a write can come back empty — that's expected latency, not broken recall.\n- **`db_path` allowlist:** writes and recalls must target `~/.memory/**` when the host enforces permissions.\n- **Provenance is retrieval signals, not a source URL.** `provenance` reports which of `vec`/`fts`/`temporal` matched — cite the `uid`, and keep the actual source in the node's content or metadata.\n\n## Examples\n\n- *Recall before researching:* `memory_recall({query:\"token cost optimization for multi-agent dispatch\", token_budget:50000, limit:5})` — reuse the top findings by `uid`, research only the gap.\n- *Write a finding:* `memory_write({content:\"Thin orchestrator holds only board + state deltas; executors hold working context.\", project_path:\"/Users/you/repo\", source:\"document\", agent_id:\"workflow-researcher\", metadata:{topic:\"execution-context-partition\"}})`.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}