Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Context Types
OpenViking resources provide reference material, memories retain information from interactions, and skills describe how to carry out tasks. Rules (Beta) are a separate type of mandatory constraint that an Agent must follow when its conditions hold.
Overview
| Type | Purpose | Lifecycle | Initiative |
|---|---|---|---|
| Resource | Source knowledge and reference material | Retained until updated or deleted | User adds |
| Memory | Preferences, facts, and task experience | Long-term, dynamically updated | Extracted from sessions or recorded explicitly |
| Skill | Task instructions and supporting resources | Long-term, updatable | User or system adds |
| Rule (Beta) | Durable, executable mandatory constraints | active / paused / archived | Explicit compilation and on-demand recall |
Example Setup
The examples below use the synchronous Python SDK and an existing server. add_resource and add_skill take wait=True to block until processing finishes. Session commits return before memory extraction finishes and have no built-in wait, so this helper polls the commit task before dependent searches. A polling timeout does not cancel the server task.
import time
from openviking_sdk import SyncHTTPClient
client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")
def wait_for_task(task_id):
deadline = time.monotonic() + 300
while time.monotonic() < deadline:
task = client.get_task(task_id)
if task is None:
raise RuntimeError(f"Task {task_id} not found")
if task["status"] == "completed":
return task
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(1)
raise TimeoutError(f"Task {task_id} is still running")
Resource
Resources are external knowledge that Agents can reference.
Characteristics
- User-driven: Resource information actively added by users to supplement LLM knowledge, such as product manuals and code repositories
- Explicit updates: Re-import changed content, or use a Watch to refresh supported remote sources
- Structured storage: Organized by project or topic in directory hierarchy, with multi-layer information extraction
Examples
- API docs, product manuals
- FAQ databases, code repositories
- Research papers, technical specs
Usage
# Add resource
client.add_resource(
path="https://docs.example.com/api.pdf",
options={"reason": "API documentation"},
wait=True,
timeout=300,
)
# Search resources
results = client.find(
query="authentication methods",
target_uri="viking://resources/",
)
Memory
Memories are durable knowledge learned from interactions and task execution. They are stored in the current User or Peer namespace, not in a separate viking://agent/memories directory.
Characteristics
- Agent-driven: Memory information actively extracted and recorded by Agent
- Dynamic updates: Continuously updated from interactions by Agent
- Personalized: Learned for specific users and stable peers
Built-in Memory Types
| Type | Default location | Description |
|---|---|---|
| profile | ~/memories/profile.md |
Basic user information |
| preferences | ~/memories/preferences/ |
User preferences organized by topic |
| entities | ~/memories/entities/ |
Knowledge about people, projects, organizations, and other entities |
| events | ~/memories/events/ |
Decisions, milestones, and other event records |
| identity | ~/memories/identity.md |
Assistant name, persona, temperament, and self-introduction |
| soul | ~/memories/soul.md |
Assistant principles, boundaries, style, and continuity |
| cases | ~/memories/cases/ |
Task cases used for training and evaluation |
| trajectories | ~/memories/trajectories/ |
Reusable task-execution trajectories |
| experiences | ~/memories/experiences/ |
Reusable experience distilled from execution outcomes |
The ~/... entries above use the home alias viking://~, which the server expands to viking://user/{user_id}/... for the authenticated caller. When the memory policy permits Peer memory, supported types may instead be written under viking://user/{user_id}/peers/{peer_id}/memories/.... Applications can extend or adjust memory types with custom templates.
The schema-defined memories/tools/ and memories/skills/ types are disabled. They are separate from standalone Skills stored under viking://user/{user_id}/skills/{skill_name}/SKILL.md, which remain supported.
Usage
from openviking_sdk import TextPart
# Memories are auto-extracted from sessions
session_info = client.create_session()
session = client.session(session_id=session_info["session_id"])
session.add_message(
role="user",
parts=[TextPart(text="I prefer dark mode")],
)
commit = session.commit() # Starts background memory extraction
if commit.get("task_id"):
wait_for_task(commit["task_id"])
# Search memories
results = client.find(
query="UI preferences",
target_uri="viking://~/memories/"
)
Skill (Capabilities / AgentDefinedContextType)
A Skill uses SKILL.md and supporting files to describe a task’s steps, constraints, and resources. An agent reads the Skill and carries out the task using its own tools. Execution experience can be stored separately as memory.
Characteristics
- Task instructions: Steps and constraints for completing a type of work
- Maintainable: Skill content can be updated; execution experience is stored separately
- Read on demand: The agent selects skills for its current task
Storage Location
viking://~/skills/{skill-name}/ # Default storage path
├── .abstract.md # L0: Short description
├── .overview.md # L1: Directory overview (after generation)
├── SKILL.md # L2: Skill definition
└── scripts # L2: Supporting implementation
viking://agent/skills/{skill-name}/ # Override via -p/--parent-auto-create, public/shared (account global)
├── .abstract.md # L0: Short description
├── .overview.md # L1: Directory overview (after generation)
├── SKILL.md # L2: Skill definition
└── scripts # L2: Supporting implementation
AgentDefinedContextType Subtypes
The table below lists the design categories for shared capabilities. Skills are supported and installed in the user-private directory by default, with an option to use viking://agent/skills/. The other categories are planned and do not imply available APIs:
| Subtype | Location | Description |
|---|---|---|
| Skill | agent/skills/ |
Traditional workflow definitions, such as search and code generation |
| Endpoint | agent/endpoints/ |
Communication endpoint configuration (a2a, anp, etc.) (planned) |
| Tool | agent/tools/ |
Tool configuration (mcp, etc.) (planned) |
| Payment | agent/payments/ |
Payment capability configuration (ap2, etc.) (planned) |
Usage
# Add skill (defaults to viking://~/skills/)
client.add_skill(
data={
"name": "search-web",
"description": "Search the web for information",
"content": "# search-web\n...",
},
wait=True,
timeout=300,
)
# Search user skills
results = client.find(
query="web search",
target_uri="viking://~/skills/"
)
# Search global agent skills
results = client.find(
query="web search",
target_uri="viking://agent/skills/",
)
Install into the account-shared skills directory with the CLI (requires write access to that path):
ov skills add ./skills/search-web -p viking://agent/skills
Unified Search
A single retrieval can return resources, memories, and skills within its search scope. The default includes the current user's space and shared resources; add viking://agent/skills explicitly to include shared Skills:
# Search across all context types
results = client.find(
query="user authentication",
target_uri=["viking://~", "viking://resources", "viking://agent/skills"],
)
for context in results.get("memories", []):
print(f"Memory: {context['uri']}")
for context in results.get("resources", []):
print(f"Resource: {context['uri']}")
for context in results.get("skills", []):
print(f"Skill: {context['uri']}")
Close the client when these operations are finished:
client.close()
Related Documents
- Architecture Overview - System architecture
- Context Layers - L0/L1/L2 model
- Viking URI - URI specification
- Session Management - Memory extraction mechanism