@pyxmate/memory 0.20.5 → 0.21.2

package/skills/pyx-memory/SKILL.md

@@ -1,128 +0,0 @@
----
-name: pyx-memory
-description: >
-  Persistent memory system for AI agents — store and retrieve knowledge across
-  conversations via pyx-memory. Use this skill whenever you need to remember
-  something for later, recall what was discussed or decided in a prior session,
-  search stored memory before assuming, store a decision or bug-fix root cause,
-  or ingest files, documents, or images into long-term memory. Also use it for
-  the lifecycle and wiki primitives: building a per-entity profile or "wiki
-  page" (summarizeEntity / getEntitySynthesis — an amortized "tell me about
-  X / give me a profile of this customer" synthesis that is computed once and
-  reused); browsing a chronological feed of what was added and when (memory
-  log — "what has the agent learned", "what's new since last week"); linting
-  memory health (orphaned graph nodes, stale syntheses, dedup candidates); and
-  consolidation, decay, or session summarization. Use it for any integration
-  work with the pyx-memory SDK, MemoryClient, or HTTP API — including
-  multi-tenant isolation, fine-grained ReBAC (namespaces, principals, authz
-  tuples, AuthzPlan), sensitivity classification, encryption at rest, and
-  confidence/abstention scoring. Trigger this skill even when the user does
-  not say "pyx-memory" by name: phrases like "remember this", "what did we
-  decide", "recall earlier context", "store this decision", "search memory",
-  "give me a profile of <person/customer>", "summarize everything we know
-  about X", "what has the agent learned", or "set up per-agent / per-tenant
-  memory isolation" all indicate this skill should be used. When in doubt
-  about whether a request involves agent memory, prefer using this skill.
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(curl *)
-argument-hint: "[store|search|ingest] <content or query>"
----
-
-# pyx-memory — Agent Memory System
-
-Persistent memory across conversations. Store what you learn, search before you assume.
-
-## Configuration
-
-Your endpoint and API key are in the project's CLAUDE.md or agent config. Look for a `## Persistent Memory` or `## Memory System` section.
-
-If no credentials are configured, skip to [SDK Integration](#sdk-integration) below.
-
-Operations below use the `pyxmate-memory` CLI (ships with `@pyxmate/memory`).
-Set `PYXMATE_API_KEY` and `PYXMATE_ENDPOINT` once; for multi-tenant servers add `--tenant-id <id>`.
-
-## Store: after important events
-
-Immediately after any of these events, store a memory before continuing:
-
-- **User corrects you** ("no, do it this way", "don't use X") → store the correction and why
-- **A bug is fixed** → store the root cause and solution
-- **An architecture or design decision is made** → store the decision and reasoning
-- **An integration detail is discovered** (API format, auth flow, endpoint) → store it
-- **A gotcha or pitfall is encountered** → store what went wrong and the fix
-- **The user states a preference** about workflow or tools → store it
-- **The user explicitly says "remember this"** → store immediately
-
-```bash
-pyxmate-memory store \
-  --content "WHAT_HAPPENED" --topic TOPIC --project PROJECT_NAME --source agent
-```
-
-When the memory mentions named people, tools, or organizations, pass `--entities '<json>'` and `--relationships '<json>'` (or `@path.json` / `-` for stdin) to populate the knowledge graph. See [reference/http-api.md](reference/http-api.md) for entity and relationship types.
-
-## Search: before making assumptions
-
-Search for relevant context in these situations:
-
-- **Starting a new conversation or task** → search for the project name and task topic
-- **Before suggesting an approach** → check if a prior decision contradicts it
-- **User references prior work** ("like we did before", "remember when") → search for it
-- **Investigating a bug** → search if it was seen before
-
-```bash
-pyxmate-memory search --query "QUERY" --limit 5
-```
-
-## Ingest files & images: when a file is worth remembering
-
-Upload files directly when the content is worth persisting — diagrams, screenshots, documents, data files.
-
-- **User shares a document or image** and says "remember this" or "store this" → ingest it
-- **A screenshot captures important context** (error screen, architecture diagram, UI state) → ingest with a description
-- **A document contains reference material** (spec, config, report) → ingest it
-
-```bash
-pyxmate-memory ingest-file path/to/file --description "What this file contains or shows"
-```
-
-Supported formats: txt, md, csv, tsv, log, pdf, docx, xlsx, pptx, json, jsonl, html, htm, png, jpg, jpeg, webp, gif, bmp, tiff, svg (100MB limit).
-
-Ingestion memory profile, by format:
-
-- **Plain-text + structured-text** (`csv`, `tsv`, `txt`, `log`, `json`, `jsonl`, `html`, `htm`, `md`): truly streaming — peak memory ≈ a few MB regardless of file size, up to the 100 MB file cap.
-- **`pdf`**: streaming via the poppler `pdftotext` first-class path — peak memory ≈ a few MB. The `pdf-parse` fallback (when poppler is absent) loads the whole buffer; install poppler-utils for streaming.
-- **`xlsx`**: row-by-row streaming via `ExcelJS.stream.xlsx.WorkbookReader`, but **shared strings are cached for the whole workbook** (`sharedStrings: 'cache'`). Peak memory grows with shared-string count, not just file size — workbooks with dense, repeated cell strings can use significantly more memory than the file cap suggests.
-- **`pptx`**: the full ZIP is decompressed in memory (same shape as docx); only one slide's XML is decoded at a time. For a typical 30 MB presentation, peak memory is ~90 MB. Capped at 100 MB file / 200 MB decompressed.
-- **`docx`**: hard-capped at 10 MB. The underlying library (mammoth) has no streaming API and loads the whole document into memory; above 10 MB the server returns a `MemoryError` asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
-- **Images** (`png`, `jpg`, `jpeg`, `webp`, `gif`, `bmp`, `tiff`, `svg`): the file is held in memory once for embedding/storage; size scales with the file, not with content complexity.
-
-If you need deterministic memory or timing for production UX (e.g. RAG over large user-supplied workbooks), prefer pre-extracting `.pptx` and large `.xlsx` upstream and uploading the text as `.txt`. See `patterns/file-uploads.md` for the consumer-side pattern.
-
-**Images require a `description`** — this is how the content gets embedded and becomes searchable. Without it, the image is stored but not findable. Use your vision capabilities to generate the description when the user doesn't provide one.
-
-**Documents don't need a `description`** — text content is extracted and chunked automatically.
-
-## Rules
-
-- Always include `topic` and `project` in metadata
-- Keep content factual and concise — decisions, not deliberation
-- Do NOT store ephemeral info (file contents, current state, in-progress work)
-- One memory per concept — don't bundle unrelated things
-- Extract entities when content mentions specific people, tools, technologies, organizations, locations, or events by name
-
----
-
-## SDK Integration
-
-For integrating pyx-memory into TypeScript/Bun projects, see the reference docs:
-
-| What you need | Where to look |
-|---|---|
-| Wire pyx-memory into a consumer project | [patterns/consumer.md](patterns/consumer.md) |
-| Set up embedded memory (full features) | [patterns/embedded.md](patterns/embedded.md) |
-| Multi-tenant, ReBAC (namespaces + tuples), sensitivity, encryption | [patterns/access-control.md](patterns/access-control.md) |
-| SDK quick start, package map, DO/DON'T | [reference/sdk-guide.md](reference/sdk-guide.md) |
-| HTTP API endpoints | [reference/http-api.md](reference/http-api.md) |
-| Type signatures and interfaces | [reference/types.md](reference/types.md) |
-| RAG strategies, bi-temporal, consolidation | [reference/advanced.md](reference/advanced.md) |
-| Feature parity: embedded vs sidecar | [reference/parity.md](reference/parity.md) |
-| Minimal code examples | [examples/](examples/) |

package/skills/pyx-memory/examples/disabled-memory.ts

@@ -1,53 +0,0 @@
-import type { MemoryInterface, MemoryListResult } from '@pyx-memory/client';
-import type { MemoryEntry, MemorySearchResult, MemoryStats } from '@pyx-memory/shared';
-
-export class DisabledMemory implements MemoryInterface {
-  async initialize(): Promise<void> {
-    console.warn('Memory service not configured — running without memory');
-  }
-  async store(
-    entry: Omit<MemoryEntry, 'id' | 'createdAt'> & { id?: string; createdAt?: string },
-  ): Promise<MemoryEntry> {
-    return {
-      id: '',
-      content: entry.content,
-      type: entry.type,
-      metadata: {},
-      createdAt: new Date().toISOString(),
-    };
-  }
-  async search(): Promise<MemorySearchResult> {
-    return { entries: [], totalCount: 0, strategy: 'naive' };
-  }
-  async list(): Promise<MemoryListResult> {
-    return { entries: [], totalCount: 0, page: 1, limit: 20 };
-  }
-  async get(): Promise<MemoryEntry | null> {
-    return null;
-  }
-  async delete(): Promise<boolean> {
-    return false;
-  }
-  async clearSession(): Promise<number> {
-    return 0;
-  }
-  async stats(): Promise<MemoryStats> {
-    return {
-      totalEntries: 0,
-      storageUsedBytes: 0,
-      vectorCount: 0,
-      recentAccessCount: 0,
-      connected: false,
-    };
-  }
-  async shutdown(): Promise<void> {}
-}
-
-// Usage: pick the right implementation based on config
-import { MemoryClient } from '@pyx-memory/client';
-
-const memory: MemoryInterface = process.env.MEMORY_URL
-  ? new MemoryClient(process.env.MEMORY_URL, process.env.MEMORY_API_KEY)
-  : new DisabledMemory();
-
-await memory.initialize();

package/skills/pyx-memory/examples/minimal-embedded.ts

@@ -1,37 +0,0 @@
-import { Memory } from '@pyx-memory/core';
-
-const memory = new Memory({ dataDir: './data' });
-await memory.initialize(); // REQUIRED — throws if you skip this
-
-// Store (default targets: sqlite + vector)
-await memory.store({
-  content: 'User prefers dark mode',
-  type: 'long-term',
-  metadata: { source: 'settings' },
-});
-
-// Store with entities — populates the knowledge graph
-await memory.store({
-  content: 'Alice switched the project to TypeScript for type safety',
-  type: 'long-term',
-  metadata: { source: 'decisions' },
-  entities: [
-    { name: 'Alice', type: 'PERSON' },
-    { name: 'TypeScript', type: 'TOOL' },
-  ],
-  relationships: [{ source: 'Alice', target: 'TypeScript', type: 'USES' }],
-});
-
-// Store with explicit targets (e.g., sqlite only)
-await memory.store({
-  content: 'Temporary working note',
-  type: 'working',
-  metadata: {},
-  targets: ['sqlite'],
-});
-
-// Search
-const _results = await memory.search({ query: 'user preferences', limit: 5 });
-
-// Cleanup
-await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources

package/skills/pyx-memory/examples/minimal-sidecar.ts

@@ -1,14 +0,0 @@
-import { MemoryClient } from '@pyx-memory/client';
-
-// Without auth (local dev)
-const memory = new MemoryClient('http://localhost:7822');
-
-// With auth (production — pass API key as second argument)
-// const memory = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
-
-await memory.initialize(); // verifies server connectivity via /health
-
-await memory.store({ content: 'Important fact', type: 'long-term', metadata: {} });
-const _results = await memory.search({ query: 'fact', limit: 5 });
-
-// Start the server: bun packages/server/src/index.ts