Python SDK

The official Python client for SharedMemory.

pip install sharedmemory-ai

Requires Python 3.8+.

Authenticate with Authorization: Bearer sm_…. Prefer sm_org_rw_… / sm_proj_rw_… from Settings → API Keys, or sm_agent_…, sm_live_… (sm login).

Quick Start

from sharedmemory import SharedMemory

memory = SharedMemory(
    api_key="sm_org_rw_...",
    volume_id="your-project-id",
)

# Store a memory
result = memory.add("User prefers dark mode and compact layout")

# Query memories
results = memory.query("user preferences")
for source in results["sources"]:
    print(source["content"], source["score"])

Configuration

Option	Type	Default	Description
api_key	str	—	Required. Bearer secret (sm_org_rw_…, sm_proj_rw_…, sm_agent_…, etc.)
base_url	str	https://api.sharedmemory.ai	API endpoint
volume_id	str	"default"	Default project (volume) for all operations
user_id	str	—	Scope memories to a specific user
agent_id	str	—	Scope memories to a specific agent
agent_name	str	"python-sdk"	Agent name for attribution
timeout	float	30.0	Request timeout in seconds
app_id	str	—	App identifier for scoping
session_id	str	—	Default session ID

Methods

Memory

Method	Description
remember(content, **opts)	Store a memory
query(query, **opts)	Query memories (semantic search)
chat(query, **opts)	Ask a question — LLM answers using your memories
get(memory_id)	Get a single memory by ID
update(memory_id, content)	Update a memory
delete(memory_id)	Delete a memory
remember_many(items)	Store multiple memories in batch
delete_many(memory_ids)	Delete multiple memories by ID
update_many(updates)	Update multiple memories in batch
feedback(memory_id, feedback, reason?)	Submit feedback on a memory
history(memory_id)	Get memory audit trail

Sessions

Method	Description
start_session(session_id, **opts)	Start a conversation session
end_session(session_id, auto_summarize?)	End session with optional summarization
get_session(session_id)	Get session details
list_sessions(**opts)	List sessions with optional filters

Webhooks

Method	Description
webhook_subscribe(url, events, secret?)	Register a webhook endpoint
webhook_unsubscribe(url)	Remove a webhook subscription

Export / Import

Method	Description
export_memories(**opts)	Export memories from a volume
import_memories(memories, **opts)	Import memories into a volume

Extraction

Method	Description
extract(text, schema_id, **opts)	Extract structured data from text

Graph

Method	Description
get_entity(name)	Get entity details and relationships
search_entities(query, **opts)	Search entities in the knowledge graph by name
get_graph()	Retrieve the full knowledge graph
list_volumes()	List all volumes accessible by this API key

Context

Method	Description
get_context(template_id?)	Get optimized context for LLM prompting

Agent Management

Method	Description
create_agent(org_id, project_id, name, **opts)	Create a new agent profile
list_agents(org_id, project_id?)	List agents in an organization
get_agent(agent_id)	Get agent details
update_agent(agent_id, **opts)	Update agent settings
delete_agent(agent_id)	Delete an agent
rotate_agent_key(agent_id)	Rotate an agent's API key

Organization Management

Method	Description
list_orgs()	List organizations you belong to
get_org(org_id)	Get organization details
list_org_members(org_id)	List members of an organization
apply_promo(org_id, code)	Apply a promo code

Entity Scoping

Scope memories to specific users, agents, or sessions:

memory = SharedMemory(
    api_key="sm_org_rw_...",
    volume_id="vol-uuid",
    user_id="user-123",
    agent_id="chatbot-1",
)

# All operations are automatically scoped
memory.remember("User asked about pricing", session_id="sess-abc")
results = memory.query("pricing", session_id="sess-abc")

Advanced Search

# With reranking
results = memory.query(
    "project deadlines",
    rerank=True,
    rerank_method="llm",
    include_context=True,
)

# With metadata filters
results = memory.query("preferences", filters={
    "AND": [
        {"field": "memory_class", "op": "eq", "value": "preference"},
        {"field": "score", "op": "gte", "value": 0.5},
    ]
})

Batch Operations

# Delete multiple memories
memory.delete_many(["mem-id-1", "mem-id-2", "mem-id-3"])

# Update multiple memories (each item must have memory_id AND content)
memory.update_many([
    {"memory_id": "mem-id-1", "content": "Updated content"},
    {"memory_id": "mem-id-2", "content": "Reviewed and updated"},
])

Webhooks

# Subscribe to memory events
memory.webhook_subscribe(
    url="https://my-server.com/webhook",
    events=["memory.approved", "memory.flagged"],
    secret="my-signing-secret",  # optional HMAC-SHA256
)

# Unsubscribe
memory.webhook_unsubscribe(url="https://my-server.com/webhook")

Deliveries are retried up to 3 times with exponential backoff. Webhooks are auto-disabled after 10 consecutive failures.

Export / Import

# Export all memories
data = memory.export_memories()
print(len(data))  # list of memory dicts

# Import memories
memory.import_memories([
    {"content": "Alice is VP of Engineering", "memory_type": "factual"},
    {"content": "Bob manages frontend", "memory_type": "factual"},
])

Structured Extraction

extracted = memory.extract(
    "John Smith is the CTO of Acme Corp",
    schema_id="schema-uuid",
)

Agent Management

# Create an agent
agent = memory.create_agent("org-id", "project-id", "support-bot", description="CS assistant")

# List agents
agents = memory.list_agents("org-id")

# Rotate an agent key
new_key = memory.rotate_agent_key(agent["id"])

Organization Management

orgs = memory.list_orgs()
members = memory.list_org_members(orgs[0]["id"])
memory.apply_promo(orgs[0]["id"], "PROMO-CODE")

Async Client

For async/await usage:

from sharedmemory.async_client import AsyncSharedMemory

memory = AsyncSharedMemory(
    api_key="sm_org_rw_...",
    volume_id="your-project-id",
)

result = await memory.add("User prefers dark mode")
results = await memory.search("preferences")

PyPI

https://pypi.org/project/sharedmemory-ai/

License

MIT