Commit Session

POST

api

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

import requests

url = "https://api.example.com/api/v1/sessions/{session_id}/commit"

payload = {
    "profile": {},
    "preferences": {},
    "entities": {},
    "events": {},
    "cases": {},
    "patterns": {}
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    profile: {},
    preferences: {},
    entities: {},
    events: {},
    cases: {},
    patterns: {}
  })
};

fetch('https://api.example.com/api/v1/sessions/{session_id}/commit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/sessions/{session_id}/commit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'profile' => [
        
    ],
    'preferences' => [
        
    ],
    'entities' => [
        
    ],
    'events' => [
        
    ],
    'cases' => [
        
    ],
    'patterns' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/sessions/{session_id}/commit"

	payload := strings.NewReader("{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/sessions/{session_id}/commit")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/sessions/{session_id}/commit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}"

response = http.request(request)
puts response.read_body

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

Archives current messages to history/archive_N/
Extracts memories into 6 categories (profile, preferences, entities, events, cases, patterns)
Clears active message buffer
Updates context usage statistics

Request

Path Parameters

string

required

The session ID to commit

Headers

string

required

Your OpenViking API key for authentication

string

default:"application/json"

Must be application/json

Response

string

Response status (ok or error)

object

Commit operation result

string

The session identifier

string

Commit status (usually committed)

boolean

Whether messages were archived

number

Number of long-term memories extracted

number

Number of context usage records updated

object

Session statistics

number

Total conversation turns (user messages)

number

Number of contexts referenced

number

Number of skills called

number

Total memories extracted across all commits

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"

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

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

# Create and use session
session = client.session()

# Add conversation
session.add_message("user", [
    TextPart(text="How do I configure embedding?")
])

# Search and add response
results = client.search("embedding configuration", session=session)
session.add_message("assistant", [
    TextPart(text="You can configure embedding in config.yaml..."),
    ContextPart(
        uri=results.resources[0].uri,
        context_type="resource",
        abstract=results.resources[0].abstract
    )
])

# Track usage
session.used(contexts=[results.resources[0].uri])

# Commit session
result = session.commit()

print(f"Status: {result['status']}")
print(f"Archived: {result['archived']}")
print(f"Memories extracted: {result['memories_extracted']}")
print(f"Active count updated: {result['active_count_updated']}")

import requests

response = requests.post(
    "http://localhost:1933/api/v1/sessions/a1b2c3d4/commit",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
    }
)

result = response.json()
print(f"Memories extracted: {result['result']['memories_extracted']}")

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

category

Location: viking://user/{user}/memories/profile.mdUser profile information (name, role, background, expertise)Merge strategy: Always merged into single profile.md file

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

category

Location: viking://user/{user}/memories/entities/Important entities (people, projects, organizations, concepts)Merge strategy: Merged when referring to same entity

category

Location: viking://user/{user}/memories/events/Significant events (decisions, milestones, incidents)Merge strategy: Created as separate events, not merged

Agent Memories

category

Location: viking://agent/{agent}/memories/cases/Problem-solution pairs (specific bugs fixed, issues resolved)Merge strategy: Created as separate cases, not merged

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

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

⌘I

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

import requests

url = "https://api.example.com/api/v1/sessions/{session_id}/commit"

payload = {
    "profile": {},
    "preferences": {},
    "entities": {},
    "events": {},
    "cases": {},
    "patterns": {}
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    profile: {},
    preferences: {},
    entities: {},
    events: {},
    cases: {},
    patterns: {}
  })
};

fetch('https://api.example.com/api/v1/sessions/{session_id}/commit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/sessions/{session_id}/commit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'profile' => [
        
    ],
    'preferences' => [
        
    ],
    'entities' => [
        
    ],
    'events' => [
        
    ],
    'cases' => [
        
    ],
    'patterns' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/sessions/{session_id}/commit"

	payload := strings.NewReader("{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/sessions/{session_id}/commit")
  .header("X-API-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/sessions/{session_id}/commit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"profile\": {},\n  \"preferences\": {},\n  \"entities\": {},\n  \"events\": {},\n  \"cases\": {},\n  \"patterns\": {}\n}"

response = http.request(request)
puts response.read_body

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

Overview

Resources

Filesystem

Search & Retrieval

Sessions

Skills

System

Admin

Request

Path Parameters

Headers

Response

Examples

Response Example

Memory Extraction Categories

User Memories

Agent Memories

Memory Structure

Archive Structure

When to Commit

Auto-commit by Token Count

Commit at Natural Boundaries

Full Lifecycle Example

Best Practices

Always Track Usage Before Commit

Commit Regularly

Check Commit Results

​Request

​Path Parameters

​Headers

​Response

​Examples

​Response Example

​Memory Extraction Categories

​User Memories

​Agent Memories

​Memory Structure

​Archive Structure

​When to Commit

​Auto-commit by Token Count

​Commit at Natural Boundaries

​Full Lifecycle Example

​Best Practices

​Always Track Usage Before Commit

​Commit Regularly

​Check Commit Results

​Related Endpoints

Request

Path Parameters

Headers

Response

Examples

Response Example

Memory Extraction Categories

User Memories

Agent Memories

Memory Structure

Archive Structure

When to Commit

Auto-commit by Token Count

Commit at Natural Boundaries

Full Lifecycle Example

Best Practices

Always Track Usage Before Commit

Commit Regularly

Check Commit Results

Related Endpoints