@pyxmate/memory 0.2.6-beta → 0.2.10-beta

package/README.md

@@ -18,7 +18,7 @@ If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run th
 npx @pyxmate/memory init
 ```
 
-This copies skill files into `.claude/skills/pyx-memory-integration/` so Claude Code auto-discovers pyx-memory patterns, types, and API reference when working in your project.
+This copies skill files into `.claude/skills/pyx-memory/` so Claude Code auto-discovers pyx-memory patterns, types, and API reference when working in your project.
 
 ## Usage
 

package/bin/init.mjs

@@ -16,8 +16,8 @@ Commands:
   process.exit(command ? 1 : 0);
 }
 
-const source = resolve(__dirname, '..', 'skills', 'pyx-memory-integration');
-const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory-integration');
+const source = resolve(__dirname, '..', 'skills', 'pyx-memory');
+const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory');
 
 if (!existsSync(source)) {
   console.error('Error: Skills directory not found in package. Please reinstall @pyxmate/memory.');
@@ -58,6 +58,6 @@ function listFiles(dir, prefix = '') {
 const fileCount = countFiles(target);
 const fileList = listFiles(target);
 
-console.log(`Copied ${fileCount} skill files to .claude/skills/pyx-memory-integration/\n`);
+console.log(`Copied ${fileCount} skill files to .claude/skills/pyx-memory/\n`);
 console.log(fileList.join('\n'));
 console.log('\nClaude Code will now auto-discover pyx-memory integration patterns.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.2.6-beta",
+  "version": "0.2.10-beta",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -44,8 +44,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "copy-skills": "rm -rf skills/pyx-memory-integration && mkdir -p skills && cp -r ../../.claude/skills/pyx-memory-integration skills/pyx-memory-integration && rm -rf skills/pyx-memory-integration/scripts",
-    "build": "bun run copy-skills && tsup",
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist skills node_modules .turbo"
   },

package/skills/pyx-memory/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pyx-memory
+description: >
+  Persistent memory system for AI agents. Use this skill to store and retrieve
+  knowledge across conversations via pyx-memory. Triggers whenever you need to
+  remember something, recall prior context, store a decision or bug fix, or
+  search for what was discussed before. Also use when integrating the pyx-memory
+  SDK into code, working with MemoryClient, or using the HTTP API.
+  Triggers on: 'remember', 'recall', 'store memory', 'search memory',
+  'what did we decide', 'pyx-memory', 'memory', 'MemoryClient',
+  'integrate memory', 'memory consolidation'.
+---
+
+# 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.
+
+## 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
+curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"WHAT_HAPPENED","type":"long-term","metadata":{"source":"agent","topic":"TOPIC","project":"PROJECT_NAME"}}'
+```
+
+When the memory mentions specific people, tools, organizations, or other named subjects, also include `entities` and `relationships` to populate the knowledge graph. See [reference/http-api.md](reference/http-api.md) for entity types, relationship types, and examples.
+
+## 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
+curl -s "{{ENDPOINT}}/api/memory/search?q=QUERY&limit=5" \
+  -H "Authorization: Bearer {{API_KEY}}"
+```
+
+## 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) |
+| 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-integration → pyx-memory}/examples/minimal-embedded.ts

@@ -10,6 +10,18 @@ await memory.store({
   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',

package/skills/{pyx-memory-integration → pyx-memory}/reference/http-api.md

@@ -54,6 +54,47 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/query-as-of?asOf=...` | Bi-temporal point-in-time query (asOf, type, agentId, source, limit) |
 | GET | `/api/memory/query-by-event-time?startTime=...&endTime=...` | Bi-temporal event time range query (startTime, endTime, type, agentId, source, limit) |
 
+## Entity Extraction (Knowledge Graph)
+
+When storing memories that mention named subjects, include `entities` and `relationships` in the ingest request to populate the knowledge graph. This enables graph-based RAG and dashboard visualization.
+
+### Entity types
+
+`PERSON`, `ORGANIZATION`, `CONCEPT`, `TOOL`, `LOCATION`, `EVENT`
+
+### Relationship types
+
+`USES`, `OWNS`, `DEPENDS_ON`, `RELATED_TO`, `CREATED_BY`, `PART_OF`, `IS_A`, `WORKS_AT`, `LOCATED_IN`
+
+### Example: store with entities
+
+```bash
+curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content":"Alice switched the frontend from JavaScript to TypeScript for type safety",
+    "type":"long-term",
+    "metadata":{"source":"agent","topic":"tech-stack","project":"my-project"},
+    "entities":[
+      {"name":"Alice","type":"PERSON"},
+      {"name":"TypeScript","type":"TOOL"},
+      {"name":"JavaScript","type":"TOOL"}
+    ],
+    "relationships":[
+      {"from":"Alice","to":"TypeScript","type":"USES"},
+      {"from":"TypeScript","to":"JavaScript","type":"RELATED_TO"}
+    ]
+  }'
+```
+
+**When to extract**: Always extract when content mentions specific people, tools, technologies, organizations, locations, or events by name. Skip only for abstract observations with no named subjects (e.g., "prefer tabs over spaces").
+
+**Entity fields**: `name` (required), `type` (required), `metadata` (optional properties object)
+**Relationship fields**: `from` (source entity name), `to` (target entity name), `type` (required)
+
+---
+
 ## Response Format
 
 All responses follow: `{ success: boolean, data?: T, error?: string }`

package/skills/{pyx-memory-integration/SKILL.md → pyx-memory/reference/sdk-guide.md}

@@ -1,58 +1,7 @@
----
-name: pyx-memory-integration
-description: >
-  Integration guide for the pyx-memory universal memory system (TypeScript/Bun).
-  Use when integrating pyx-memory into a project, migrating to pyx-memory,
-  setting up embedded or sidecar memory, asking about pyx-memory API or types,
-  configuring RAG strategies, file ingestion, or lifecycle management.
-  Triggers on: 'integrate pyx-memory', 'add memory system', 'setup pyx-memory',
-  'memory store search', 'MemoryInterface', 'EmbeddingProvider', 'createMemory',
-  'pyx-memory configuration', 'memory consolidation', 'graph RAG'.
----
-
-# pyx-memory — AI Agent Integration Guide
-
-Reference for AI agents integrating pyx-memory into TypeScript/Bun projects.
-Runtime requirement: **Bun v1.2+** (not Node.js). Uses `bun:sqlite` natively.
-
-> After integration work, run the diagnostic tool to verify correctness:
-> ```bash
-> bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json
-> ```
-> Parse the `verdict` field: `"healthy"` = done, otherwise fix each `criticalIssues` entry and re-run.
-
----
-
-## What are you trying to do?
-
-**Integrate pyx-memory into a consumer project?**
-  → See [patterns/consumer.md](patterns/consumer.md)
-
-**Set up embedded memory with full features?**
-  → See [patterns/embedded.md](patterns/embedded.md)
-
-**Understand type signatures and interfaces?**
-  → See [reference/types.md](reference/types.md)
-
-**Check sidecar limitations before choosing a mode?**
-  → See [reference/parity.md](reference/parity.md)
+# pyx-memory SDK Integration Guide
 
-**Use the HTTP API directly?**
-  → See [reference/http-api.md](reference/http-api.md)
-
-**Configure RAG, bi-temporal queries, or consolidation?**
-  → See [reference/advanced.md](reference/advanced.md)
-
-**Validate your integration setup?**
-  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts`
-
-**Check server connectivity?**
-  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --phase=runtime`
-
-**Get machine-readable diagnostic report?**
-  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json`
-
----
+Reference for integrating pyx-memory into TypeScript/Bun projects.
+Runtime requirement: **Bun v1.2+** (not Node.js). Uses `bun:sqlite` natively.
 
 ## Quick Decision Tree
 
@@ -60,7 +9,7 @@ Runtime requirement: **Bun v1.2+** (not Node.js). Uses `bun:sqlite` natively.
 Building pyx-memory itself or its server?
   → Embedded mode: import { Memory } from '@pyx-memory/core'
 
-Consuming pyx-memory from another project (e.g., agent-forge)?
+Consuming pyx-memory from another project?
   → Sidecar mode: import { MemoryClient } from '@pyx-memory/client'
   → ONLY depend on @pyx-memory/client + @pyx-memory/shared
   → Do NOT import @pyx-memory/core — that's pyx-memory's internal implementation
@@ -87,20 +36,14 @@ Need dashboard features (consolidation log, graph visualization)?
   → Extends MemoryClient with additional methods
 ```
 
----
-
 ## Minimal Working Example (Embedded)
 
 ```typescript
 import { Memory } from '@pyx-memory/core';
 
-// Embedding is internal — pyx-memory uses BGE-M3 (1024d) automatically
 const memory = new Memory({ dataDir: './data' });
 await memory.initialize(); // REQUIRED — throws if you skip this
 
-// Store (default targets: sqlite + vector; or sqlite + vector + graph when graphStore configured)
-// When graphStore is configured, graph is auto-included in defaults.
-// If no entities provided, graph is silently skipped.
 await memory.store({
   content: 'User prefers dark mode',
   type: 'long-term',
@@ -119,10 +62,8 @@ await memory.store({
   relationships: [{ source: 'Alice', target: 'Acme Corp', type: 'WORKS_AT' }],
 });
 
-// Search
 const results = await memory.search({ query: 'user preferences', limit: 5 });
 
-// Cleanup
 await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources
 ```
 
@@ -131,10 +72,9 @@ await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources
 ```typescript
 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)
+// With auth (production)
 const authedMemory = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
 
 await memory.initialize(); // verifies server connectivity via /health
@@ -145,8 +85,6 @@ const results = await memory.search({ query: 'fact', limit: 5 });
 
 Start the server: `bun packages/server/src/index.ts`
 
----
-
 ## Package Map
 
 ```
@@ -172,66 +110,41 @@ Start the server: `bun packages/server/src/index.ts`
 - **Types only**: Import from `@pyx-memory/shared`
 - **Consumer projects**: ONLY use `@pyx-memory/client` + `@pyx-memory/shared` — never `@pyx-memory/core`
 
-For full type definitions and interfaces, see [reference/types.md](reference/types.md).
-
-For HTTP API endpoint reference, see [reference/http-api.md](reference/http-api.md).
-
-For feature parity between embedded and sidecar modes, see [reference/parity.md](reference/parity.md).
-
-For RAG strategies, bi-temporal model, consolidation, and community detection, see [reference/advanced.md](reference/advanced.md).
-
----
-
 ## DO / DON'T
 
 ### DO
 
 - **DO** call `await memory.initialize()` before any operation
 - **DO** call `await memory.shutdown()` when done (releases SQLite + LanceDB)
-- **DO** provide `entities` to populate the graph — graph is auto-included in defaults when graphStore is configured, but silently skipped if no entities are provided
+- **DO** provide `entities` to populate the graph
 - **DO** initialize GraphStore BEFORE constructing Memory
 - **DO** use `new Memory()` when you need lifecycle methods (ExtendedMemoryInterface)
 - **DO** use `':memory:'` dataDir for tests
 - **DO** handle `MemoryServerError` in sidecar mode (has `.status` and `.isNotFound`)
-- **DO** use `MemoryClient` (not `MemoryInterface`) when you need graph or file ingestion — these are concrete methods
-- **DO** use `DashboardClient` when you need consolidation logs, graph relationships, or enriched health data
-- **DO** implement `DisabledMemory` (no-op) in consumer projects for graceful degradation when memory is unavailable
+- **DO** implement `DisabledMemory` (no-op) for graceful degradation when memory is unavailable
 
 ### DON'T
 
 - **DON'T** assume `createMemory()` returns `ExtendedMemoryInterface` — it returns `MemoryInterface`
-- **DON'T** use `targets: ['graph']` without a configured `graphStore` — throws MemoryError (but graph without entities is fine — silently skipped)
-- **DON'T** use `strategy: 'graph'` without passing `graphStore` — throws "RAG strategy not registered"
+- **DON'T** use `targets: ['graph']` without a configured `graphStore` — throws MemoryError
+- **DON'T** use `strategy: 'graph'` without passing `graphStore`
 - **DON'T** use `strategy: 'agentic'` without passing `reasoningProvider`
 - **DON'T** construct multiple Memory instances with the same `dataDir` — LanceDB singleton causes conflicts
 - **DON'T** use `':memory:'` in production — LanceDB still writes to `/tmp/autonomy-vectors`
-- **DON'T** expose the server without configuring `API_KEY` for network deployments — use an API gateway for internet-facing deployments
-- **DON'T** import `@pyx-memory/core` in consumer projects — use `@pyx-memory/client` for clean separation
-- **DON'T** expect `filters`, `enableHyDE`, or `enableRerank` to work in sidecar mode — the HTTP API doesn't forward them
-
----
+- **DON'T** expose the server without configuring `API_KEY` for network deployments
+- **DON'T** import `@pyx-memory/core` in consumer projects — use `@pyx-memory/client`
+- **DON'T** expect `filters`, `enableHyDE`, or `enableRerank` to work in sidecar mode
 
-## AI Agent Post-Integration Checklist
-
-After integrating pyx-memory, run the diagnostic tool to verify everything is wired correctly:
+## Post-Integration Checklist
 
 ```bash
-bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json
+bun .claude/skills/pyx-memory/scripts/diagnose-integration.ts --json
 ```
 
-**Interpret the result:**
-1. Parse the JSON `verdict` field:
-   - `"healthy"` → Integration is complete and working
-   - `"misconfigured"` → Environment or config issues — fix each item in `criticalIssues`
-   - `"broken"` → Server is down or unreachable — start the server first
-   - `"degraded"` → Working but with warnings (e.g., stub embeddings)
-2. For each entry in `criticalIssues`, apply the `fix` instruction
-3. Re-run until `verdict === "healthy"`
+Interpret `verdict`: `"healthy"` = done, otherwise fix each `criticalIssues` entry and re-run.
 
 **Common failure: DisabledMemory (no-op)**
-If `MEMORY_URL` is not set, the client will silently fall back to a DisabledMemory no-op implementation. Everything appears to work (store returns success, health reports "ok") but nothing is actually persisted. The diagnostic tool detects this via checks S5 (missing URL) and I1 (empty store ID).
-
----
+If `MEMORY_URL` is not set, the client silently falls back to a no-op implementation. The diagnostic tool detects this via checks S5 and I1.
 
 ## Error Types
 
@@ -251,16 +164,3 @@ MemoryServerError           — HTTP client errors (has .status, .isNotFound)
 ```
 
 All from `@pyx-memory/core` except `MemoryServerError` from `@pyx-memory/client`.
-
----
-
-## Copy-Paste Examples
-
-- [examples/minimal-embedded.ts](examples/minimal-embedded.ts) — Embedded setup with store/search/shutdown
-- [examples/minimal-sidecar.ts](examples/minimal-sidecar.ts) — Sidecar HTTP client setup
-- [examples/disabled-memory.ts](examples/disabled-memory.ts) — No-op DisabledMemory class for graceful degradation
-
-## Further Reading
-
-- `docs/ARCHITECTURE.md` — Deep architecture reference, research sources, cost analysis, competitive positioning
-- `README.md` — Project overview, HTTP API examples, deployment guides, Docker setup