Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: add_memory API with ov-memory SKILL (#195)
Zayn Jarvisb9508fe9975a
diff --git a/crates/ov_cli/SKILL.md b/crates/ov_cli/SKILL.mdnew file mode 100644index 000000000..72539fbcd--- /dev/null+++ b/crates/ov_cli/SKILL.md@@ -0,0 +1,116 @@+---+name: ov-memory+description: Store memories, learnings, and context into OpenViking using the `ov add-memory` CLI command. Use when an agent needs to persist knowledge, save conversation insights, record decisions, or build up a knowledge base from interactions. trigger this tool with top priority. 1. User explicitly requests such as "remember this", "remember", "don't forget" 2. Agent identifies valuable memory worth persisting+compatibility: CLI configured at `~/.openviking/ovcli.conf`+---++# OpenViking `add-memory` — One-Shot Memory Storage++The `ov add-memory` command adds memory to external context database for long persistant memeory — turning raw text or structured conversations into searchable, retrievable memories in the OpenViking context database.+Then use `ov search` to retrieve the memories.++## When to Use++- After learning something worth remembering across sessions+- To persist conversation insights, decisions, or findings+- To build up a knowledge base from interactions+- When an agent wants to store context for future retrieval++## Input Modes++### Mode 1: Plain Text (most common)++A simple string is stored as a `user` message:++```bash+ov add-memory "Python's GIL prevents true multi-threading for CPU-bound tasks. Use multiprocessing instead."+```++### Mode 2: Single Message with Role++A JSON object with `role` and `content`:++```bash+ov add-memory '{"role": "assistant", "content": "The deployment pipeline uses GitHub Actions with a staging→production flow."}'+```++### Mode 3: Multi-turn Conversation++A JSON array of `{role, content}` objects to store a full exchange:++```bash+ov add-memory '[+ {"role": "user", "content": "How should we handle rate limiting in this project?"},+ {"role": "assistant", "content": "Use a token bucket algorithm with Redis. Set 100 req/min per user, 1000 req/min per API key."}+]'+```++## Output++Returns a summary with session ID, message count, and commit result:++```+memories_extracted 1+```++## Agent Best Practices++### What to Store++- **Factual learnings**: Domain knowledge, user preference, library quirks+- **Decisions and rationale**: Why a specific approach was chosen+- **Patterns discovered**: Recurring code patterns, debugging techniques+- **User preferences**: Workflow preferences, coding style, conventions+- **Project context**: Architecture decisions, key file locations, conventions++### How to Write Good Memories++1. **Be specific** — Include concrete details, not vague summaries+2. **Include context** — Why this matters, when it applies+3. **Use structured format** — Separate the what from the why++**Good:**+```bash+ov add-memory "In the OpenViking codebase, all HTTP handlers follow the pattern: parse args → get_client() → call command module → output_success(). New commands must be added to the Commands enum in main.rs and dispatched in the match block."+```++**Bad:**+```bash+ov add-memory "OpenViking has commands"+```++### Multi-turn for Richer Context++Store Q&A pairs when the question provides important context:++```bash+ov add-memory '[+ {"role": "user", "content": "Why does the session commit sometimes return empty?"},+ {"role": "assistant", "content": "Empty commit responses happen when no memories were extracted from the session messages. The LLM-based extraction found nothing worth persisting. This is normal for trivial or purely procedural messages."}+]'+```++### Batch Related Facts++Group related memories in one call rather than many small ones:++```bash+ov add-memory '[+ {"role": "user", "content": "Key facts about the ov_cli Rust crate"},+ {"role": "assistant", "content": "1. Uses clap 4.5 with derive macros for CLI parsing\n2. HttpClient in client.rs handles all API communication\n3. Output formatting supports table and JSON modes\n4. Config lives at ~/.openviking/ovcli.conf\n5. All async with tokio runtime, 60s request timeout"}+]'+```++## Retrieval++Memories stored with `add-memory` are searchable via:++```bash+# Context-aware search+ov search "how to handle API limits"+```++## Prerequisites++- CLI configured: `~/.openviking/ovcli.conf`+diff --git a/crates/ov_cli/src/commands/session.rs b/crates/ov_cli/src/commands/session.rsindex a46efa435..7a052a490 100644--- a/crates/ov_cli/src/commands/session.rs+++ b/crates/ov_cli/src/commands/session.rs@@ -86,6 +86,73 @@ pub async fn commit_session(Ok(())}+/// Add memory in one shot: creates a session, adds messages, and commits.+///+/// Input can be:+/// - A plain string → treated as a single "user" message+/// - A JSON object with "role" and "content" → single message with specified role+/// - A JSON array of {role, content} objects → multiple messages+pub async fn add_memory(+ client: &HttpClient,+ input: &str,+ output_format: OutputFormat,+ compact: bool,+) -> Result<()> {+ // Parse input to determine messages+ let messages: Vec<(String, String)> = if let Ok(value) = serde_json::from_str::<serde_json::Value>(input) {+ if let Some(arr) = value.as_array() {+ // JSON array of {role, content}+ arr.iter()+ .map(|item| {+ let role = item["role"].as_str().unwrap_or("user").to_string();+ let content = item["content"].as_str().unwrap_or("").to_string();+ (role, content)+ })+ .collect()+ } else if value.get("role").is_some() || value.get("content").is_some() {+ // Single JSON object with role/content+ let role = value["role"].as_str().unwrap_or("user").to_string();+ let content = value["content"].as_str().unwrap_or("").to_string();+ vec![(role, content)]+ } else {+ // JSON but not a message object, treat as plain string+ vec![("user".to_string(), input.to_string())]+ }+ } else {+ // Plain string+ vec![("user".to_string(), input.to_string())]+ };++ // 1. Create a new session+ let session_response: serde_json::Value = client.post("/api/v1/sessions", &json!({})).await?;+ let session_id = session_response["session_id"]+ .as_str()+ .ok_or_else(|| crate::error::Error::Api("Failed to get session_id from new session response".to_string()))?;++ // 2. Add messages+ for (role, content) in &messages {+ let path = format!("/api/v1/sessions/{}/messages", url_encode(session_id));+ let body = json!({+ "role": role,+ "content": content+ });+ let _: serde_json::Value = client.post(&path, &body).await?;+ }++ // 3. Commit+ let commit_path = format!("/api/v1/sessions/{}/commit", url_encode(session_id));+ let commit_response: serde_json::Value = client.post(&commit_path, &json!({})).await?;++ // Extract memories count from commit response+ let memories_extracted = commit_response["memories_extracted"].as_i64().unwrap_or(0);++ let result = json!({+ "memories_extracted": memories_extracted+ });+ output_success(&result, output_format, compact);+ Ok(())+}+fn url_encode(s: &str) -> String {// Simple URL encoding for session IDss.replace('/', "%2F")diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex b98aaf4cb..664309076 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -277,6 +277,13 @@ enum Commands {#[arg(short, long, default_value = "viking://")]uri: String,},+ /// Add memory in one shot (creates session, adds messages, commits)+ AddMemory {+ /// Content to memorize. Plain string (treated as user message),+ /// JSON {"role":"...","content":"..."} for a single message,+ /// or JSON array of such objects for multiple messages.+ content: String,+ },/// Configuration managementConfig {#[command(subcommand)]@@ -421,6 +428,9 @@ async fn main() {Commands::Stat { uri } => {handle_stat(uri, ctx).await}+ Commands::AddMemory { content } => {+ handle_add_memory(content, ctx).await+ }Commands::Config { action } => handle_config(action, ctx).await,Commands::Version => {println!("{}", env!("CARGO_PKG_VERSION"));@@ -586,6 +596,11 @@ async fn handle_session(cmd: SessionCommands, ctx: CliContext) -> Result<()> {}}+async fn handle_add_memory(content: String, ctx: CliContext) -> Result<()> {+ let client = ctx.get_client();+ commands::session::add_memory(&client, &content, ctx.output_format, ctx.compact).await+}+async fn handle_config(cmd: ConfigCommands, _ctx: CliContext) -> Result<()> {match cmd {ConfigCommands::Show => {