python-sdk-and-cli

Python SDK And CLI

Use this sub-skill when a task names memmachine_client, MemMachineClient, Project, Memory, Config, mem-cli, memmachine, Python memory add or search, semantic categories/tags/features, metadata filters, agent_mode, or LangGraph memory tools.

Route Within This Sub-skill

• Read python-sdk-reference.md for the verified Python object model, method signatures, and return-shape notes.
• Read memory-workflows.md for project/context setup, add/search/list/delete, semantic feature/category/tag workflows, filters, and validation patterns.
• Read cli-reference.md for mem-cli and memmachine command shapes, environment variables, JSON flags, and safe examples.
• Read troubleshooting.md when imports, base URLs, project context, filters, closed clients, or server responses fail.
• Run mem_cli_smoke.py to inspect CLI parser/help or build safe command examples without contacting a server.
• Run python_client_recipe.py to print a minimal Python SDK recipe or optionally run a live health/add/search demo only when explicit live arguments are supplied.

Quick Python Pattern

from memmachine_client import MemMachineClient

client = MemMachineClient(base_url="http://localhost:8080", api_key=None)
try:
    project = client.get_or_create_project(org_id="my-org", project_id="my-project")
    memory = project.memory(
        metadata={"user_id": "alice", "agent_id": "assistant", "session_id": "demo"}
    )
    memory.add("Alice prefers aisle seats.", metadata={"category": "travel"})
    results = memory.search("What seating does Alice prefer?", limit=5)
finally:
    client.close()

Use explicit org_id, project_id, and memory metadata instead of relying on ambient defaults. Keep API keys in environment variables or secret stores.

Quick CLI Pattern

mem-cli --base-url "http://localhost:8080" memory add \
  "Alice prefers aisle seats." \
  --org-id "my-org" --project-id "my-project" \
  --metadata user_id=alice --metadata agent_id=assistant \
  --metadata category=travel

mem-cli --base-url "http://localhost:8080" memory search \
  "What seating does Alice prefer?" \
  --org-id "my-org" --project-id "my-project" --limit 5

Global flags such as --base-url and --api-key come before the subcommand. Project context flags belong on projects or memory subcommands.

Decision Points

• SDK or CLI? Use SDK for application code and tests; use CLI for ad-hoc inspection, shell workflows, and agent memory retrieval/addition.
• Filter style? Use modern filter="metadata.category = 'travel'" for boolean logic. Use filter_dict only for simple legacy equality filters.
• Semantic or episodic? MemoryType supports episodic and semantic. Adding to both may be useful, but verify the server configuration supports both before assuming results appear in both surfaces.
• Agent mode? agent_mode=True asks the server retrieval agent to do richer query handling. It needs server-side LLM/reranker resources; use ordinary search first for simple lookups.
• LangGraph tools? Use MemMachineTools or helper factories when an agent runtime expects callable add/search tools. Ensure framework dependencies are installed separately.

Non-goals And Cross-links

• Server YAML, storage/provider resources, Docker, MCP, and REST deployment details belong in server-configuration-and-memory-engines.
• Framework adapters beyond the Python LangGraph helper surface belong in integrations-and-migration.
• @memmachine/client belongs in typescript-rest-client.
• Endpoint/model translation details shared across SDKs are in the root REST API and data models reference.