tools-only Sessions
Sessions manage conversation state, track context usage, and extract long-term memories.
API Reference
create_session()
Create a new session.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| session_id | str | No | None | Session ID. Creates new session with auto-generated ID if None |
| user | str | No | None | User identifier (HTTP API only) |
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data", user="alice")
client.initialize()
# Create new session (auto-generated ID)
session = client.session()
print(f"Session URI: {session.uri}")
client.close()
HTTP API
POST /api/v1/sessions
curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"user": "alice"
}'
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
"user": "alice"
},
"time": 0.1
}
list_sessions()
List all sessions.
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
sessions = client.ls("viking://session/")
for s in sessions:
print(f"{s['name']}")
client.close()
HTTP API
GET /api/v1/sessions
curl -X GET http://localhost:1933/api/v1/sessions \
-H "X-API-Key: your-key"
Response
{
"status": "ok",
"result": [
{"session_id": "a1b2c3d4", "user": "alice"},
{"session_id": "e5f6g7h8", "user": "bob"}
],
"time": 0.1
}
get_session()
Get session details.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| session_id | str | Yes | - | Session ID |
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
# Load existing session
session = client.session(session_id="a1b2c3d4")
session.load()
print(f"Loaded {len(session.messages)} messages")
client.close()
HTTP API
GET /api/v1/sessions/{session_id}
curl -X GET http://localhost:1933/api/v1/sessions/a1b2c3d4 \
-H "X-API-Key: your-key"
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
"user": "alice",
"message_count": 5
},
"time": 0.1
}
delete_session()
Delete a session.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| session_id | str | Yes | - | Session ID to delete |
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
client.rm("viking://session/a1b2c3d4/", recursive=True)
client.close()
HTTP API
DELETE /api/v1/sessions/{session_id}
curl -X DELETE http://localhost:1933/api/v1/sessions/a1b2c3d4 \
-H "X-API-Key: your-key"
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4"
},
"time": 0.1
}
add_message()
Add a message to the session.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| role | str | Yes | - | Message role: "user" or "assistant" |
| parts | List[Part] | Yes | - | List of message parts (SDK) |
| content | str | Yes | - | Message text content (HTTP API) |
Part Types (Python SDK)
from openviking.message import TextPart, ContextPart, ToolPart
# Text content
TextPart(text="Hello, how can I help?")
# Context reference
ContextPart(
uri="viking://resources/docs/auth/",
context_type="resource", # "resource", "memory", or "skill"
abstract="Authentication guide..."
)
# Tool call
ToolPart(
tool_id="call_123",
tool_name="search_web",
skill_uri="viking://skills/search-web/",
tool_input={"query": "OAuth best practices"},
tool_output="",
tool_status="pending" # "pending", "running", "completed", "error"
)
Python SDK
import openviking as ov
from openviking.message import TextPart
client = ov.OpenViking(path="./data")
client.initialize()
session = client.session()
# Add user message
session.add_message("user", [
TextPart(text="How do I authenticate users?")
])
# Add assistant response
session.add_message("assistant", [
TextPart(text="You can use OAuth 2.0 for authentication...")
])
client.close()
HTTP API
POST /api/v1/sessions/{session_id}/messages
# Add user message
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"role": "user",
"content": "How do I authenticate users?"
}'
# Add assistant message
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"role": "assistant",
"content": "You can use OAuth 2.0 for authentication..."
}'
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
"message_count": 2
},
"time": 0.1
}
compress()
Compress a session by archiving messages and generating summaries.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| session_id | str | Yes | - | Session ID to compress |
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
session = client.session(session_id="a1b2c3d4")
session.load()
# Commit archives messages and extracts memories
result = session.commit()
print(f"Status: {result['status']}")
print(f"Memories extracted: {result['memories_extracted']}")
client.close()
HTTP API
POST /api/v1/sessions/{session_id}/compress
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/compress \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
"status": "compressed",
"archived": true
},
"time": 0.1
}
extract()
Extract memories from a session.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| session_id | str | Yes | - | Session ID to extract memories from |
Python SDK
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
session = client.session(session_id="a1b2c3d4")
session.load()
# Commit includes memory extraction
result = session.commit()
print(f"Memories extracted: {result['memories_extracted']}")
client.close()
HTTP API
POST /api/v1/sessions/{session_id}/extract
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
Response
{
"status": "ok",
"result": {
"session_id": "a1b2c3d4",
"memories_extracted": 3
},
"time": 0.1
}
Session Properties
| Property | Type | Description |
|---|---|---|
| uri | str | Session Viking URI (viking://session/{session_id}/) |
| messages | List[Message] | Current messages in the session |
| stats | SessionStats | Session statistics |
| summary | str | Compression summary |
| usage_records | List[Usage] | Context and skill usage records |
Session Storage Structure
viking://session/{session_id}/
+-- .abstract.md # L0: Session overview
+-- .overview.md # L1: Key decisions
+-- messages.jsonl # Current messages
+-- tools/ # Tool executions
| +-- {tool_id}/
| +-- tool.json
+-- .meta.json # Metadata
+-- .relations.json # Related contexts
+-- history/ # Archived history
+-- archive_001/
| +-- messages.jsonl
| +-- .abstract.md
| +-- .overview.md
+-- archive_002/
Memory Categories
| Category | Location | Description |
|---|---|---|
| profile | user/memories/.overview.md |
User profile information |
| preferences | user/memories/preferences/ |
User preferences by topic |
| entities | user/memories/entities/ |
Important entities (people, projects) |
| events | user/memories/events/ |
Significant events |
| cases | agent/memories/cases/ |
Problem-solution cases |
| patterns | agent/memories/patterns/ |
Interaction patterns |
Full Example
Python SDK
import openviking as ov
from openviking.message import TextPart, ContextPart
# Initialize client
client = ov.OpenViking(path="./my_data")
client.initialize()
# Create new session
session = client.session()
# Add user message
session.add_message("user", [
TextPart(text="How do I configure embedding?")
])
# Search with session context
results = client.search("embedding configuration", session=session)
# Add assistant response with context reference
session.add_message("assistant", [
TextPart(text="Based on the documentation, you can configure embedding..."),
ContextPart(
uri=results.resources[0].uri,
context_type="resource",
abstract=results.resources[0].abstract
)
])
# Track actually used contexts
session.used(contexts=[results.resources[0].uri])
# Commit session (archive messages, extract memories)
result = session.commit()
print(f"Memories extracted: {result['memories_extracted']}")
client.close()
HTTP API
# Step 1: Create session
curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"user": "alice"}'
# Returns: {"status": "ok", "result": {"session_id": "a1b2c3d4", "user": "alice"}}
# Step 2: Add user message
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"role": "user", "content": "How do I configure embedding?"}'
# Step 3: Search with session context
curl -X POST http://localhost:1933/api/v1/search/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"query": "embedding configuration", "session_id": "a1b2c3d4"}'
# Step 4: Add assistant message
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"role": "assistant", "content": "Based on the documentation, you can configure embedding..."}'
# Step 5: Extract memories
curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key"
Best Practices
Commit Regularly
# Commit after significant interactions
if len(session.messages) > 10:
session.commit()
Track What's Actually Used
# Only mark contexts that were actually helpful
if context_was_useful:
session.used(contexts=[ctx.uri])
Use Session Context for Search
# Better search results with conversation context
results = client.search(query, session=session)
Load Before Continuing
# Always load when resuming an existing session
session = client.session(session_id="existing-id")
session.load()
Related Documentation
- Context Types - Memory types
- Retrieval - Search with session
- Resources - Resource management