Python SDK

Full reference for the agentrecall-sdk Python package.

Installation

pip install agentrecall-sdk

Quick Start

The fastest way to get started with cloud mode:

# 1. Create an agent in the dashboard
# 2. Create an API key for that agent
# 3. Use the key — agent_id is automatic

from agentrecall_sdk import AgentRecall

memory = AgentRecall(api_key="ark_your_api_key")

# No need to pass agent_id — it's bound to your API key
memory.store("User prefers dark mode")
results = memory.search("UI preferences")

Setup

Cloud Mode (Recommended)

API keys are agent-specific. Each key is tied to one agent, so you don't need to pass agent_id in every call.

from agentrecall_sdk import AgentRecall

memory = AgentRecall(
    api_key="ark_your_api_key",  # bound to a specific agent
    mode="cloud",  # default
    base_url="https://api.agentrecall.cloud"  # optional
)

Local Mode

memory = AgentRecall(
    mode="local",
    neo4j_uri="bolt://localhost:7687",
    neo4j_user="neo4j",
    neo4j_password="password",
    model_path="Qwen/Qwen2.5-7B"  # optional
)

API Reference

`store()`

Parameter	Type	Required	Description
`content`	str	Yes	Memory text content
`agent_id`	str	No*	Agent identifier. Auto-inferred from API key. Required only with JWT auth.
`category`	str	No	Memory category
`metadata`	dict	No	Extra key-value data
`importance`	float	No	Manual importance (0–1)
`process`	bool	No	Enable AI processing (default: True)

# With API key (agent_id is automatic)
result = memory.store(
    content="User prefers TypeScript over JavaScript",
    category="preferences",
    metadata={"source": "code_review"},
    importance=0.7
)

# With JWT auth (agent_id required)
result = memory.store(
    content="User prefers TypeScript",
    agent_id="coding-assistant",
)
print(result.id)  # "mem_abc123"

`search()`

Parameter	Type	Required	Description
`query`	str	Yes	Natural language search query
`agent_id`	str	No*	Agent scope. Auto-inferred from API key.
`category`	str	No	Filter by category
`limit`	int	No	Max results (default: 10)
`min_score`	float	No	Minimum relevance score

results = memory.search(
    query="what are the user's coding preferences?",
    category="preferences",
    limit=5
)

for r in results:
    print(f"[{r.score:.2f}] {r.content}")

`traverse()`

Parameter	Type	Required	Description
`entity`	str	Yes*	Starting entity name
`source`	str	Yes*	Source entity (for path finding)
`target`	str	No	Target entity (for path finding)
`depth`	int	No	Traversal depth (default: 2)
`agent_id`	str	No*	Agent scope. Auto-inferred from API key.

# Find connections from an entity
connections = memory.traverse(entity="User", depth=3)

# Find shortest path between two entities
paths = memory.traverse(source="User", target="San Francisco")

`agent()`

# Create a high-level agent with memory
agent = memory.agent(
    agent_id="my-agent",
    system_prompt="You are a helpful assistant with memory."
)

# The agent automatically stores and retrieves memories
response = agent.chat("Remember that I like coffee")

Configuration

Option	Default	Description
`api_key`	—	Cloud API key (agent-specific)
`mode`	`"cloud"`	`"cloud"` or `"local"`
`base_url`	api.agentrecall.cloud	API endpoint
`timeout`	30	Request timeout in seconds
`retries`	3	Max retry attempts

How Agent-Specific Keys Work

When you create an API key in the dashboard, you select which agent it belongs to. This means:

No agent_id needed — The key remembers which agent it's for
Better security — Each key only accesses one agent's memories
Multiple keys — Create separate keys for different environments (dev, staging, prod)

If you need to access multiple agents from one SDK instance, use JWT auth instead and pass agent_id explicitly.