Skip to main content
POST
/
api
/
v1
/
sessions
/
{session_id}
/
commit
Commit Session
curl --request POST \
  --url https://api.example.com/api/v1/sessions/{session_id}/commit \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "profile": {},
  "preferences": {},
  "entities": {},
  "events": {},
  "cases": {},
  "patterns": {}
}
'
{
  "status": "<string>",
  "result": {
    "session_id": "<string>",
    "status": "<string>",
    "archived": true,
    "memories_extracted": 123,
    "active_count_updated": 123,
    "stats": {
      "total_turns": 123,
      "contexts_used": 123,
      "skills_used": 123,
      "memories_extracted": 123
    }
  },
  "time": 123
}
Commit a session to archive its messages and extract long-term memories. This operation:
  1. Archives current messages to history/archive_N/
  2. Extracts memories into 6 categories (profile, preferences, entities, events, cases, patterns)
  3. Clears active message buffer
  4. Updates context usage statistics

​
Request

​
Path Parameters

​
session_id
string
required
The session ID to commit

​
Headers

​
X-API-Key
string
required
Your OpenViking API key for authentication
​
Content-Type
string
default:"application/json"
Must be application/json

​
Response

​
status
string
Response status (ok or error)
​
result
object
Commit operation result
​
session_id
string
The session identifier
​
status
string
Commit status (usually committed)
​
archived
boolean
Whether messages were archived
​
memories_extracted
number
Number of long-term memories extracted
​
active_count_updated
number
Number of context usage records updated
​
stats
object
Session statistics
​
total_turns
number
Total conversation turns (user messages)
​
contexts_used
number
Number of contexts referenced
​
skills_used
number
Number of skills called
​
memories_extracted
number
Total memories extracted across all commits
​
time
number
Request processing time in seconds

​
Examples

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/commit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key"

​
Response Example

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "status": "committed",
    "archived": true,
    "memories_extracted": 3,
    "active_count_updated": 2,
    "stats": {
      "total_turns": 5,
      "contexts_used": 2,
      "skills_used": 1,
      "memories_extracted": 3
    }
  },
  "time": 2.5
}

​
Memory Extraction Categories

The commit operation extracts memories into 6 categories:

​
User Memories

​
profile
category
Location: viking://user/{user}/memories/profile.mdUser profile information (name, role, background, expertise)Merge strategy: Always merged into single profile.md file
​
preferences
category
Location: viking://user/{user}/memories/preferences/User preferences organized by topic (coding style, communication style, tool preferences)Merge strategy: Merged by topic when similar
​
entities
category
Location: viking://user/{user}/memories/entities/Important entities (people, projects, organizations, concepts)Merge strategy: Merged when referring to same entity
​
events
category
Location: viking://user/{user}/memories/events/Significant events (decisions, milestones, incidents)Merge strategy: Created as separate events, not merged

​
Agent Memories

​
cases
category
Location: viking://agent/{agent}/memories/cases/Problem-solution pairs (specific bugs fixed, issues resolved)Merge strategy: Created as separate cases, not merged
​
patterns
category
Location: viking://agent/{agent}/memories/patterns/Reusable patterns (workflows, processes, interaction patterns)Merge strategy: Merged when similar patterns detected

​
Memory Structure

Each memory is stored with three levels: 
# L0: Abstract (.abstract.md)
One-sentence summary for quick scanning

# L1: Overview (.overview.md)
Medium-detail description with key points

# L2: Content (file.md)
Full narrative with complete context and details

​
Archive Structure

Committed messages are archived in: 
viking://session/{user_space}/{session_id}/history/
├── archive_001/
│   ├── messages.jsonl      # Archived messages
│   ├── .abstract.md        # L0: Archive summary
│   └── .overview.md        # L1: Archive overview
├── archive_002/
│   ├── messages.jsonl
│   ├── .abstract.md
│   └── .overview.md
└── ...

​
When to Commit

​
Auto-commit by Token Count

session = client.session(session_id="a1b2c3d4")
session.load()

# Check token usage
if session.stats.total_tokens > 8000:
    result = session.commit()
    print(f"Auto-committed: {result['memories_extracted']} memories extracted")

​
Commit at Natural Boundaries

# After completing a task
if task_completed:
    session.commit()

# End of conversation
if user_says_goodbye:
    session.commit()

# After significant interaction
if session.stats.total_turns >= 10:
    session.commit()

​
Full Lifecycle Example

import openviking as ov
from openviking.message import TextPart, ContextPart

# Initialize
client = ov.OpenViking(path="./my_data")
client.initialize()

# Create session
session = client.session()
print(f"Session: {session.session_id}")

# Conversation turn 1
session.add_message("user", [
    TextPart(text="How do I add a new resource?")
])

results = client.search("add resource", session=session)
session.add_message("assistant", [
    TextPart(text="You can use client.add_resource()..."),
    ContextPart(
        uri=results.resources[0].uri,
        context_type="resource",
        abstract="Resource management guide"
    )
])
session.used(contexts=[results.resources[0].uri])

# Conversation turn 2
session.add_message("user", [
    TextPart(text="What about indexing?")
])

results = client.search("indexing", session=session)
session.add_message("assistant", [
    TextPart(text="Indexing happens automatically..."),
    ContextPart(
        uri=results.resources[0].uri,
        context_type="resource",
        abstract="Indexing documentation"
    )
])
session.used(contexts=[results.resources[0].uri])

# Commit at end of conversation
result = session.commit()

print(f"\nCommit Results:")
print(f"  Archived: {result['archived']}")
print(f"  Memories extracted: {result['memories_extracted']}")
print(f"  Stats: {result['stats']}")

# Session is now cleared and ready for next conversation
print(f"\nActive messages after commit: {len(session.messages)}")

client.close()

​
Best Practices

​
Always Track Usage Before Commit

# Search for context
results = client.search(query, session=session)

# Add message
session.add_message("assistant", [...])

# IMPORTANT: Track what was actually used
session.used(contexts=[results.resources[0].uri])

# Commit will use this to update active_count
session.commit()

​
Commit Regularly

Don’t let sessions grow too large: 
# Good: Commit every 10-15 turns
if session.stats.total_turns >= 10:
    session.commit()

# Good: Commit when context is high
if session.stats.total_tokens > 8000:
    session.commit()

# Avoid: Never committing (loses memory)
# Avoid: Committing too frequently (inefficient)

​
Check Commit Results

result = session.commit()

if result['memories_extracted'] == 0:
    print("Warning: No memories extracted")
    # Maybe conversation wasn't meaningful enough

if result['archived']:
    print(f"Archived {len(session.messages)} messages")