Commit Session

Archive messages and extract long-term memories from a session

POST /api/v1/sessions/{session_id}/commit

Commit Session

cURL

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": {}
}
'

200

{
  "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

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.md

User 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")

Related Endpoints

• Add Message - Add messages to session
• Get Session - Check session stats
• Create Session - Start new session
• Search - Search with session context