@pyxmate/memory 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/SKILL.md

@@ -1,23 +1,28 @@
 ---
 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, ingest
-  files or images, 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. Covers multi-tenant isolation (tenantId, TENANT_MODE),
-  fine-grained ReBAC (namespaces, principals, authz tuples, AuthzPlan),
-  sensitivity classification, encryption at rest, and confidence/abstention.
-  Triggers on: 'remember', 'recall', 'store memory', 'search memory',
-  'ingest file', 'store this image', 'remember this document',
-  'what did we decide', 'pyx-memory', 'memory', 'MemoryClient',
-  'integrate memory', 'memory consolidation', 'multi-tenant',
-  'tenant isolation', 'sensitivity', 'encryption', 'confidence',
-  'abstention', 'access control', 'RBAC', 'ReBAC', 'Zanzibar',
-  'namespace', 'principal', 'authz tuple', 'permission', 'permissions',
-  'role', 'role-based access', 'read-only', 'agent isolation',
-  'per-agent memory'.
+  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>"
 ---

package/skills/pyx-memory/reference/http-api.md

@@ -46,7 +46,7 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | POST | `/api/memory/graph/query` | Traverse (JSON: `{ nodeId, depth? }`) |
 | POST | `/api/memory/graph/clear` | Clear all graph nodes and edges (admin) |
 
-## Lifecycle (9 endpoints)
+## Lifecycle (13 endpoints)
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -59,6 +59,10 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/consolidation-log` | Audit trail |
 | 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) |
+| GET | `/api/memory/lint` | Read-only memory-wide lint report — graph orphans, decay candidates, stale syntheses, dedup candidates (v0.18.0) |
+| GET | `/api/memory/log?since=...` | Chronological feed (Karpathy `log.md`). Cursor-style via `since` created_at lower bound; also `limit`, `type`, `agentId`, `source`. Returns `{ entries, count, since? }` (v0.18.1) |
+| POST | `/api/memory/synthesis/entity` | Synthesize a per-entity profile (Karpathy "wiki page"). JSON: `{ name }`. LLM-driven; stores a pinned `_kind:'entity-summary'` entry with `_search_visibility:'on-demand'`. Returns the entry, 201 (v0.19.0) |
+| GET | `/api/memory/synthesis/entity?name=...` | Fetch a previously-synthesized entity profile. Returns `{ entry }` (`null` if none) (v0.19.0) |
 
 ## ReBAC Admin (11 endpoints)
 

package/skills/pyx-memory/reference/types.md

@@ -3,7 +3,7 @@
 ## Contents
 - Type Cheat Sheet
 - MemoryInterface (9 methods)
-- ExtendedMemoryInterface (6 lifecycle methods)
+- ExtendedMemoryInterface (10 lifecycle methods)
 - MemoryClient Constructor and Concrete Methods
 - DashboardClient
 - MemorySearchResult, MemoryEntry, MemorySearchParams
@@ -62,7 +62,7 @@ interface MemoryInterface {
 }
 ```
 
-## ExtendedMemoryInterface (adds 6 lifecycle methods)
+## ExtendedMemoryInterface (adds 10 lifecycle methods)
 
 ```typescript
 interface ExtendedMemoryInterface extends MemoryInterface {
@@ -72,9 +72,34 @@ interface ExtendedMemoryInterface extends MemoryInterface {
   runDecay(): Promise<number>;
   reindex(): Promise<void>;
   deleteBySource(source: string): Promise<number>;
+  // v0.18.0 — read-only memory-wide lint report (graph orphans, decay
+  // candidates, stale syntheses, content-hash dedup candidates).
+  lint(options?: { limit?: number }): Promise<WikiLintReport>;
+  // v0.18.1 — chronological feed (Karpathy log.md primitive). Cursor-style
+  // via `since` (created_at lower bound). No totalCount.
+  log(filters?: MemoryLogFilters): Promise<MemoryEntry[]>;
+  // v0.19.0 — entity synthesis (Karpathy "wiki page" primitive).
+  // summarizeEntity is LLM-driven and caller-triggered; it stores a pinned
+  // `_kind:'entity-summary'` entry with `_search_visibility:'on-demand'`
+  // (excluded from search). getEntitySynthesis is the O(1) read path.
+  summarizeEntity(name: string): Promise<MemoryEntry>;
+  getEntitySynthesis(name: string): Promise<MemoryEntry | null>;
 }
 ```
 
+`MemoryLogFilters` = `{ since?: string; limit?: number; type?: MemoryType; agentId?: string; source?: string }`.
+
+### Reserved metadata conventions
+
+Some `metadata` keys carry behavior, not just data:
+
+| Key | Value | Effect |
+|-----|-------|--------|
+| `_search_visibility` | `'on-demand'` | Entry is excluded from every RAG engine's retrieval pool (v0.18.2 hook). Still reachable via `get` / `list` / `log` and deterministic-id fetch. Field absent ⇒ visible. |
+| `_kind` | `'entity-summary'` | Marks an entity synthesis. `Memory.lint` flags stale ones; the `synthesis:` id prefix is reserved for entries carrying this. |
+| `_sourceEntryIds` | `string[]` | Provenance — the entries a synthesis was built from. |
+| `_maxEventTime` | ISO string \| null | Staleness contract — `lint` flags the synthesis when a source's eventTime later exceeds this. |
+
 ## MemoryClient Constructor and Concrete Methods
 
 ```typescript
@@ -100,7 +125,7 @@ Graph queries and file ingestion are available without `@pyx-memory/core`.
 
 ```typescript
 class MemoryClient implements ExtendedMemoryInterface {
-  // ... all 15 interface methods (9 base + 6 lifecycle) ...
+  // ... all 19 interface methods (9 base + 10 lifecycle) ...
 
   // Graph operations (call pyx-memory server's graph endpoints)
   graphNodes(): Promise<GraphNode[]>;