vipune 0.3.0

A minimal memory layer for AI agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! Memory store data types.
//!
//! # Library-Only Public API
//!
//! The batch ingest API (`IngestPolicy`, `BatchIngestItemResult`, `BatchIngestResult`)
//! is part of the public library interface for external consumers (integration tests, kide, etc.)
//! even though the CLI binary (`src/main.rs`) doesn't use them directly.
//! These types are re-exported from `lib.rs` for library users.

use serde::Serialize;

/// Result type for conflict-aware add operations.
///
/// Returned by `MemoryStore::add_with_conflict()` to indicate whether
/// a memory was successfully added or conflicts were detected.
#[derive(Debug, Serialize)]
pub enum AddResult {
    /// Memory was successfully added.
    Added { id: String },
    /// Memory conflicts with existing similar memories.
    Conflicts {
        proposed: String,
        conflicts: Vec<ConflictMemory>,
    },
}

/// Details about a conflicting memory.
///
/// Provides information about memories that are similar to a proposed addition,
/// including their IDs, content, and similarity scores.
#[derive(Debug, Serialize)]
pub struct ConflictMemory {
    /// Unique identifier of the conflicting memory.
    pub id: String,
    /// Memory content that conflicts with the proposed addition.
    pub content: String,
    /// Similarity score indicating the degree of conflict (0.0 to 1.0).
    pub similarity: f64,
}

/// Policy for handling conflicts during memory ingestion.
///
/// Determines whether similar existing memories should block addition
/// or be ignored.
///
/// This enum is part of the public library API, re-exported from lib.rs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IngestPolicy {
    /// Detect and reject conflicts (similar to force=false in add_with_conflict).
    ///
    /// Returns conflict details without storing if similar memories exist
    /// with similarity >= threshold.
    ConflictAware,
    /// Force addition regardless of conflicts (similar to force=true).
    ///
    /// Bypasses conflict detection and stores the memory unconditionally.
    Force,
}

/// Result of processing a single item in a batch ingest operation.
///
/// Each item maps to its input index, enabling deterministic partial-failure handling.
///
/// This enum is part of the public library API, re-exported from lib.rs.
#[derive(Debug, Serialize)]
pub enum BatchIngestItemResult {
    /// Item was successfully added.
    Added { id: String },
    /// Item conflicted with existing memories (only for ConflictAware policy).
    Conflicts {
        proposed: String,
        conflicts: Vec<ConflictMemory>,
    },
    /// Item failed to process (empty, too long, or other errors).
    Error { message: String },
}

/// Summary result for a batch ingest operation.
///
/// Provides deterministic mapping from input indices to per-item outcomes.
///
/// This struct is part of the public library API, re-exported from lib.rs.
#[derive(Debug, Serialize)]
pub struct BatchIngestResult {
    /// Vector of results, one per input item, in the same order as input.
    ///
    /// Each element's index corresponds to the input item's position,
    /// enabling callers to identify which items succeeded, conflicted, or failed.
    pub results: Vec<BatchIngestItemResult>,
}