@pyxmate/memory

SDK + CLI for pyx-memory — Memory as a Service for AI agents.

This package ships:

• pyx-mem CLI — log in once, install the MCP server into Claude Code (or any MCP-aware host), inspect status, diagnose problems. Credentials live in the OS credential store; no plaintext token files.
• MemoryClient HTTP SDK — programmatic Node/Bun client for pyx-memory.
• Headless dashboard + React hooks — @pyxmate/memory/dashboard, @pyxmate/memory/react.

Install

npm install -g @pyxmate/memory
# or, in a project:
npm install @pyxmate/memory

ESM-only. Node ≥ 18. Native credential storage via @napi-rs/keyring (macOS Keychain, Linux libsecret / Secret Service, Windows Credential Manager). If a package manager omitted optional binaries, re-install with npm install --include=optional.

Use it from Claude Code

pyx-mem login
pyx-mem mcp install claude-code --scope user

Restart Claude Code. The 7 memory tools (search_memories, store_memory, get_memory, list_memories, delete_memory, ingest_memory_file, summarize_memory_entity) are auto-discovered via MCP Tool Search.

That's the whole setup — no extra LLM API keys. When the agent calls store_memory without supplying entities/relationships, the MCP tool auto-extracts a graph topology by asking the agent's own LLM via MCP sampling (same pattern as image-description / extractEntitiesV2 for file ingest). Your LLM, your credentials. Pass extractEntities: false on a per-call basis to opt out of auto-extraction. See graph-auto-entity-extraction-v2 for the full contract.

Drop the agent-template snippet into your project's CLAUDE.md / AGENTS.md to tell the agent WHEN to search vs store.

See the getting-started guide for the full CLI contract and exit codes.

Use it programmatically

import { MemoryClient } from '@pyxmate/memory';

const memory = new MemoryClient('https://memory.api.pyxmate.com', process.env.MEMORY_API_KEY);
await memory.initialize();

await memory.store({
  content: 'The project deadline is 2026-03-15',
  metadata: { topic: 'planning', project: 'orca', source: 'agent' },
});

const results = await memory.search({ query: 'deadline', limit: 5 });

Optional: client-side auto-extraction

MemoryClient.store(entry, options) accepts an enrichment.extractEntities callback. The SDK invokes your callback (running against your own LLM credentials), merges the result with any caller-supplied entities using case-insensitive caller-wins, and sends the populated graph data to the server. Mirrors the existing file-ingest extractEntitiesV2 pattern.

await memory.store(
  { content: 'Andrej Karpathy joined OpenAI as a co-founder in late 2015.',
    metadata: { topic: 'history', project: 'orca' } },
  {
    enrichment: {
      extractEntities: async ({ content, signal }) => {
        // Call YOUR LLM here. Return { entities, relations } matching the
        // EntityType/RelationType vocabularies. Throw on parse failures —
        // errors propagate to the caller, no silent swallow.
        return { entities: [...], relations: [...] };
      },
    },
    signal, // AbortSignal forwarded into both the callback and the fetch
  },
);

Per-call entry.extractEntities: false skips the callback entirely; entry.extractEntities: true with no callback throws a loud error (no silent no-op). The server never sees an LLM API key — it just persists what you send.

Entry Points

| Import | What you get | |--------|-------------| | @pyxmate/memory | MemoryClient, shared types, constants | | @pyxmate/memory/dashboard | Headless dashboard utilities — aggregations, graph transforms (no React) | | @pyxmate/memory/react | React hooks — useMemoryStats, useMemoryHealth, useKnowledgeGraph (requires React ≥ 18) |

Bin entry: pyx-mem.

Docs

These links point at the source repo because the npm tarball ships only the built dist/ (no markdown docs):

• getting-started — CLI + SDK quickstart, exit codes
• advanced — RAG strategies, bi-temporal queries, confidence/abstention
• types — public TypeScript types
• consumer-patterns — how to wire MemoryClient into a consumer project
• parity — embedded vs sidecar feature parity
• agent-template — CLAUDE.md / AGENTS.md snippet
• file-ingestion — file/image ingest caveats
• access-control — multi-tenant, ReBAC, sensitivity
• http-api — HTTP endpoints reference

Managed Cloud

pyx-memory is deployed as a managed cloud service at memory.pyxmate.com.

License

MIT. This SDK package and its bundled client/shared/dashboard code are MIT-licensed; see LICENSE. The repository as a whole is a mixed-license monorepo — server, engine, and internal apps are proprietary. See the per-package license map for the full mapping.