# https://github.com/yantrikos/yantrikdb 项目说明书
生成时间：2026-05-16 13:00:42 UTC
## 目录
- [Overview](#page-overview)
- [Installation](#page-installation)
- [Five-Index Architecture](#page-five-index-architecture)
- [Decoupled Write Path (LSM Architecture)](#page-decoupled-write-path)
- [Storage Engine](#page-storage-engine)
- [Core API Reference](#page-core-api)
- [Cognition Layer](#page-cognition-layer)
- [Conflict Detection and Resolution](#page-conflict-resolution)
- [MCP Server Integration](#page-mcp-server)
- [Python Bindings](#page-python-bindings)
## Overview
### 相关页面
相关主题：[Five-Index Architecture](#page-five-index-architecture), [Core API Reference](#page-core-api), [Installation](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)
- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)
- [crates/yantrikdb-core/src/cognition/narrative.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/narrative.rs)
- [crates/yantrikdb-core/src/cognition/personality_bias.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/personality_bias.rs)
- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)
- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)
# Overview
YantrikDB is a cognitive memory database system designed to model, store, and reason about complex human mental states and behaviors. It provides a unified architecture for managing episodic memories, semantic knowledge, and procedural information while supporting advanced cognitive operations such as attention spreading, belief revision, and proactive suggestion surfacing.
The system bridges traditional database storage with cognitive science principles, enabling applications that require understanding of user intent, emotional states, preferences, and behavioral patterns.
## Architecture Overview
YantrikDB follows a layered architecture that separates storage, cognitive processing, and query execution concerns.
```mermaid
graph TD
A[Python API Layer] --> B[Query DSL Engine]
B --> C[Cognition Module]
C --> D[Working Set Cache]
D --> E[SQLite Storage]
C --> F[Conflict Resolution]
C --> G[Proactive Surfacing]
C --> H[Narrative Tracking]
```
### Core Modules
| Module | Location | Purpose |
|--------|----------|---------|
| `state.rs` | `cognition/` | Defines cognitive node types, edge kinds, and universal attributes |
| `query_dsl.rs` | `cognition/` | Specifies cognitive operators (Recall, Believe, Plan, etc.) |
| `narrative.rs` | `cognition/` | Manages narrative arcs and story tracking |
| `personality_bias.rs` | `cognition/` | Models personality dimensions affecting system behavior |
| `receptivity.rs` | `cognition/` | Tracks user activity levels and notification preferences |
| `types.rs` | `base/` | Defines conflict types, trigger mechanisms, and configuration |
| `engine/query_dsl.rs` | `engine/` | Executes cognitive operators against the database |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()
## Cognitive Node Model
Every entity in YantrikDB is represented as a cognitive node with universal attributes that determine how it participates in reasoning, memory consolidation, and action selection.
### Node Kinds
The system supports 15 distinct node types representing different mental constructs:
| Kind | Persistence | Description |
|------|-------------|-------------|
| `Entity` | Yes | Physical or conceptual objects |
| `Episode` | Yes | Temporal memory of events |
| `Belief` | Yes | User-held beliefs about the world |
| `Goal` | Yes | Desired end states |
| `Task` | Yes | Actionable items with status tracking |
| `IntentHypothesis` | No | Transient intent guesses |
| `Routine` | Yes | Recurring behavioral patterns |
| `Need` | Yes | User needs (8 categories) |
| `Opportunity` | Yes | Time-bounded chances for action |
| `Risk` | Yes | Potential problems |
| `Constraint` | Yes | Safety or preference constraints |
| `Preference` | Yes | User preferences |
| `ConversationThread` | No | Transient conversation state |
| `ActionSchema` | Yes | Reusable action templates |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-180]()
### Universal Cognitive Attributes
Every node carries 11 dimensions that govern its lifecycle and behavior:
```mermaid
graph LR
A[Cognitive Node] --> B[confidence 0-1]
A --> C[activation 0-1]
A --> D[salience 0-1]
A --> E[persistence 0-1]
A --> F[valence -1 to 1]
A --> G[urgency 0-1]
A --> H[novelty 0-1]
A --> I[volatility 0-1]
A --> J[provenance]
A --> K[evidence_count]
```
The default values for each node kind vary based on their expected characteristics:
| NodeKind | confidence | salience | persistence |
|----------|------------|----------|-------------|
| Entity | 0.90 | 0.80 | 0.95 |
| Episode | 0.70 | 0.70 | 0.30 |
| Belief | 0.60 | 0.70 | 0.60 |
| Goal | 0.80 | 0.90 | 0.80 |
| Task | 0.90 | 0.80 | 0.40 |
| Need | 0.60 | 0.70 | 0.40 |
| Opportunity | 0.40 | 0.60 | 0.20 |
| Risk | 0.40 | 0.70 | 0.60 |
| Constraint | 0.90 | 0.80 | 0.95 |
| Preference | 0.60 | 0.50 | 0.85 |
| ActionSchema | 0.70 | 0.40 | 0.90 |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:280-320]()
## Cognitive Edge Model
Nodes connect through typed edges that encode semantic relationships and govern activation spreading.
### Edge Kinds
There are 15 edge types in the cognitive graph:
| Edge Kind | Transfer Factor | Type | Description |
|-----------|-----------------|------|-------------|
| `supports` | 0.7 | Positive | Evidence backing a belief |
| `contradicts` | -0.5 | Inhibitory | Evidence opposing a belief |
| `causes` | 0.8 | Positive | Causal relationship |
| `predicts` | 0.4 | Positive | Future outcome prediction |
| `prevents` | -0.6 | Inhibitory | Blocks an outcome |
| `advances_goal` | 0.6 | Positive | Progress toward goal |
| `blocks_goal` | -0.5 | Inhibitory | Impedes goal progress |
| `subtask_of` | 0.4 | Positive | Decomposition relationship |
| `requires` | 0.5 | Positive | Prerequisite relationship |
| `associated_with` | 0.3 | Moderate | General correlation |
| `instance_of` | 0.3 | Moderate | Categorization |
| `part_of` | 0.3 | Moderate | Compositional |
| `similar_to` | 0.3 | Moderate | Analogy |
| `precedes_temporally` | 0.2 | Moderate | Temporal ordering |
| `triggers` | 0.7 | Positive | Event initiation |
| `prefers` | 0.3 | Moderate | Preference relationship |
| `avoids` | -0.3 | Inhibitory | Avoidance pattern |
| `constrains` | -0.2 | Inhibitory | Limitation relationship |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:120-160]()
### Edge Behavior Methods
Each edge kind provides metadata through dedicated methods:
- `activation_transfer()` - Returns the spreading activation factor (-1.0 to 1.0)
- `is_inhibitory()` - Boolean indicating suppression behavior
- `is_epistemic()` - Whether edge participates in belief revision
- `is_causal()` - Whether edge represents causal relationships
```rust
pub fn is_inhibitory(self) -> bool {
self.activation_transfer() < 0.0
}
pub fn is_epistemic(self) -> bool {
matches!(self, Self::Supports | Self::Contradicts)
}
pub fn is_causal(self) -> bool {
matches!(self, Self::Causes | Self::Predicts | Self::Prevents)
}
```
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:180-200]()
## Cognitive Operators
The query DSL defines 10 operators that compose the cognitive processing pipeline:
| Operator | Priority | Purpose |
|----------|----------|---------|
| `Attend` | 10 | Foundation — always runs first |
| `Recall` | 9 | Critical for context retrieval |
| `Believe` | 8 | Evidence integration |
| `Compare` | 7 | Action selection |
| `Constrain` | 7 | Safety validation |
| `Plan` | 6 | Means-ends reasoning |
| `Project` | 5 | Forward simulation |
| `Anticipate` | 4 | Proactive reasoning |
| `Assess` | 3 | Meta-cognitive evaluation |
| `CoherenceCheck` | 2 | Maintenance under budget pressure |
资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:30-45]()
### Operator Parameters
Each operator accepts typed parameters:
```rust
pub struct AttendOp {
pub seeds: Vec,
pub max_hops: u32,
pub decay: f64,
}
pub struct RecallOp {
pub top_k: usize,
pub query: Option,
pub domain: Option,
}
pub struct BelieveOp {
pub evidence: EvidenceInput,
}
pub struct EvidenceInput {
pub target: Option,
pub observation: String,
pub direction: i32, // positive = confirming, negative = contradicting
}
```
资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:55-80]()
### Execution Flow
```mermaid
graph TD
A[Cognitive Query] --> B{Operator Type}
B --> C[Attend]
B --> D[Recall]
B --> E[Believe]
B --> F[Compare]
B --> G[Plan]
B --> H[Project]
B --> I[Anticipate]
B --> J[Assess]
B --> K[CoherenceCheck]
C --> L[Working Set Hydration]
L --> M[Activation Boost on Seeds]
M --> N[Spreading Activation]
N --> O[StepOutput]
```
The executor processes operators by first hydrating the working set from SQLite, then executing operator-specific logic:
```rust
fn execute_attend(&self, op: &AttendOp) -> StepOutput {
match self.db.hydrate_working_set(self.attention_config.clone()) {
Ok(mut ws) => {
let mut activated = 0;
let mut top = Vec::new();
for &seed in &op.seeds {
if let Some(node) = ws.get_mut(seed) {
let new_activation = (node.attrs.activation + 0.3).min(1.0);
node.attrs.activation = new_activation;
top.push((seed, new_activation));
activated += 1;
}
}
for &seed in &op.seeds {
activated += ws.activate_and_spread(seed, 0.3);
}
StepOutput::Attend { nodes_activated: activated, top_activated: top }
}
Err(e) => StepOutput::Error { message: format!("Attend failed: {}", e) },
}
}
```
资料来源：[crates/yantrikdb-core/src/engine/query_dsl.rs:100-130]()
## Need Categories
The system models 8 categories of human needs:
| Category | Description |
|----------|-------------|
| `Informational` | Knowledge and understanding needs |
| `Social` | Connection and relationship needs |
| `Emotional` | Affective and psychological needs |
| `Organizational` | Structure and planning needs |
| `Creative` | Self-expression and innovation needs |
| `Health` | Physical and mental wellness needs |
| `Financial` | Economic and resource needs |
| `Professional` | Career and work-related needs |
```rust
pub fn from_str(s: &str) -> Self {
match s {
"informational" => Self::Informational,
"social" => Self::Social,
"emotional" => Self::Emotional,
"organizational" => Self::Organizational,
"creative" => Self::Creative,
"health" => Self::Health,
"financial" => Self::Financial,
"professional" => Self::Professional,
_ => Self::Informational,
}
}
```
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:10-45]()
## Provenance and Reliability
Every cognitive node carries provenance metadata indicating its source:
| Provenance | Reliability Prior | Description |
|------------|-------------------|-------------|
| `Told` | 0.95 | User explicitly stated |
| `Observed` | 0.90 | Directly observed behavior |
| `Experimented` | 0.85 | Confirmed via controlled experiment |
| `Consolidated` | 0.80 | Merged from multiple sources |
| `Extracted` | 0.75 | From external documents |
| `Inferred` | 0.60 | Pattern-based inference |
| `SystemDefault` | 0.50 | Defaults — weakest trust |
```rust
pub fn reliability_prior(self) -> f64 {
match self {
Self::Told => 0.95,
Self::Observed => 0.90,
Self::Experimented => 0.85,
Self::Consolidated => 0.80,
Self::Extracted => 0.75,
Self::Inferred => 0.60,
Self::SystemDefault => 0.50,
}
}
```
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:220-250]()
## Action Kinds and Costs
The system models 8 types of actions with associated base costs:
| Action | Base Cost | Description |
|--------|-----------|-------------|
| `Abstain` | 0.0 | Explicitly decide inaction |
| `Inform` | 0.05 | Provide information |
| `Organize` | 0.10 | Structure content |
| `Suggest` | 0.15 | Propose an option |
| `Communicate` | 0.20 | Send a message |
| `Schedule` | 0.25 | Create calendar events |
| `Execute` | 0.30 | Take direct action |
| `Warn` | 0.30 | Alert about risk |
Higher cost indicates more disruption to the user.
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:250-290]()
## Conflict Resolution
The system detects and resolves conflicts between memories using policy-aware evaluation:
### Conflict Types
| Type | Default Priority | Description |
|------|------------------|-------------|
| `IdentityFact` | critical | Conflicting identity claims |
| `Preference` | high | Contradicting preferences |
| `Temporal` | high | Time-based contradictions |
| `Consolidation` | medium | During memory consolidation |
| `Minor` | low | Minor inconsistencies |
### Conflict Detection Flow
```mermaid
graph TD
A[Memory Operations] --> B[Candidate Pair Generation]
B --> C{Policy Check}
C -->|overlap_allowed| D[Flag as Conflict]
C -->|temporal_required| E{Time Validation}
E -->|Valid| D
E -->|Invalid| F[Apply Missing Time Severity]
C -->|No Policy| G[Default Behavior]
```
The conflict resolution system queries namespace-specific policies:
```sql
SELECT overlap_allowed, temporal_required, missing_time_severity
FROM relation_policies
WHERE relation_type = ?1 AND (namespace = ?2 OR namespace = '*')
ORDER BY CASE WHEN namespace = ?2 THEN 0 ELSE 1 END
```
资料来源：[crates/yantrikdb-core/src/distributed/conflict.rs:50-80]()
## Narrative Tracking
YantrikDB tracks narrative arcs to understand ongoing stories and life patterns:
### Arc Types
| Type | Description |
|------|-------------|
| `Relationship` | Interpersonal dynamics |
| `Project` | Goal-oriented endeavors |
| `Habit` | Recurring behaviors |
| `Discovery` | Learning journeys |
| `Loss` | Negative life events |
| `Recovery` | Healing processes |
### Arc Lifecycle
```mermaid
graph LR
A[Emerging] --> B[Active]
B --> C[Paused]
C -->|Resume| B
C --> D[Resolved]
C --> E[Abandoned]
A -->|Quality| E
```
### Chapter Types
Within arcs, chapters progress through phases:
| Type | Purpose |
|------|---------|
| `Setup` | Initial context setting |
| `Rising` | Building tension or progress |
| `Climax` | Peak moment |
| `Falling` | Winding down |
| `Resolution` | Final conclusion |
| `Interlude` | Pause between main chapters |
资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:30-80]()
## Personality Model
The system models personality across 8 dimensions affecting system behavior:
| Dimension | Description |
|-----------|-------------|
| `curiosity` | Drive to explore and learn |
| `proactivity` | Tendency to initiate action |
| `caution` | Risk aversion level |
| `warmth` | Emotional engagement |
| `efficiency` | Optimization preference |
| `playfulness` | Humor and levity |
| `formality` | Communication style |
| `persistence` | Follow-through tendency |
```rust
pub const DIMENSION_NAMES: [&'static str; 8] = [
"curiosity", "proactivity", "caution", "warmth",
"efficiency", "playfulness", "formality", "persistence",
];
pub fn similarity(&self, other: &Self) -> f64 {
// Cosine similarity between personality vectors
let mut dot = 0.0;
let mut mag_a = 0.0;
let mut mag_b = 0.0;
for i in 0..Self::DIMENSIONS {
let a = self.dimension(i);
let b = other.dimension(i);
dot += a * b;
mag_a += a * a;
mag_b += b * b;
}
// Normalized cosine similarity
(dot / (mag_a.sqrt() * mag_b.sqrt())).clamp(-1.0, 1.0)
}
```
资料来源：[crates/yantrikdb-core/src/cognition/personality_bias.rs:50-90]()
## User Receptivity
The system tracks user activity states to optimize notification timing:
### Activity Levels
| Level | Interruption Cost | Description |
|-------|-------------------|-------------|
| `Idle` | 0.15 | No active engagement |
| `JustReturned` | 0.35 | Recently became active |
| `Browsing` | 0.45 | Casual content consumption |
| `Communicating` | 0.50 | In active conversation |
| `TaskSwitching` | 0.55 | Mid-task context switch |
| `FocusedWork` | 0.75 | Deep concentration |
| `DeepFocus` | 0.95 | Critical focus period |
### Notification Modes
| Mode | Behavior |
|------|----------|
| `All` | All notifications allowed |
| `ImportantOnly` | Only important notifications |
| `DoNotDisturb` | Block all notifications |
资料来源：[crates/yantrikdb-core/src/cognition/receptivity.rs:20-70]()
## Think() Configuration
The cognitive loop is configured via `ThinkConfig`:
```rust
pub struct ThinkConfig {
pub importance_threshold: f64,
pub decay_threshold: f64,
pub max_triggers: usize,
}
```
### Trigger Types
| Type | Cooldown | Expiry |
|------|----------|--------|
| `DecayReview` | 3 days | 7 days |
| `ConsolidationReady` | 1 day | 3 days |
| `ConflictEscalation` | 2 days | 14 days |
| `TemporalDrift` | 14 days | 7 days |
| `Redundancy` | 1 day | 7 days |
| `RelationshipInsight` | 7 days | 7 days |
| `ValenceTrend` | 7 days | 7 days |
| `EntityAnomaly` | 7 days | 7 days |
| `PatternDiscovered` | 7 days | 7 days |
资料来源：[crates/yantrikdb-core/src/base/types.rs:100-150]()
## Python API
The system exposes a Python interface for memory operations:
```rust
#[pyo3(signature = (
query=None, embedding=None, top_k=10, memory_type=None, namespace=None,
time_window=None, expand_entities=false, include_consolidated=false,
skip_reinforce=false, domain=None, source=None
))]
fn query(
&self,
py: Python<'_>,
query: Option<&str>,
embedding: Option>,
top_k: usize,
// ... additional parameters
) -> PyResult>
```
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-90]()
## Summary
YantrikDB provides a comprehensive cognitive memory architecture featuring:
- **15 cognitive node types** with 11 universal attributes each
- **18 edge kinds** with configurable activation transfer
- **10 cognitive operators** for reasoning and context management
- **8 need categories** for human motivation modeling
- **7 provenance levels** with reliability priors
- **8 personality dimensions** for behavioral adaptation
- **6 activity states** for interruption optimization
- **Policy-aware conflict resolution** with namespace support
- **Narrative arc tracking** across 6 lifecycle states
The system balances persistent storage with working-set caching to support real-time cognitive operations while maintaining long-term memory integrity.
---
## Installation
### 相关页面
相关主题：[Overview](#page-overview), [Python Bindings](#page-python-bindings), [MCP Server Integration](#page-mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [pyproject.toml](https://github.com/yantrikos/yantrikdb/blob/main/pyproject.toml)
- [crates/yantrikdb-python/Cargo.toml](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/Cargo.toml)
- [crates/yantrikdb-python/pyproject.toml](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/pyproject.toml)
- [src/yantrikdb/__init__.py](https://github.com/yantrikos/yantrikdb/blob/main/src/yantrikdb/__init__.py)
# Installation
This guide covers all supported methods for installing YantrikDB across different platforms and use cases.
## Prerequisites
### System Requirements
| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| Python | 3.9 | 3.11+ |
| Operating System | Linux, macOS, Windows | Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), Windows (
Error with Openai API: output new_sensitive (1027)
Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.
---
## Five-Index Architecture
### 相关页面
相关主题：[Decoupled Write Path (LSM Architecture)](#page-decoupled-write-path), [Storage Engine](#page-storage-engine), [Core API Reference](#page-core-api)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-core/src/vector/hnsw.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/hnsw.rs)
- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)
- [crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)
- [crates/yantrikdb-core/src/knowledge/graph_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph_index.rs)
- [crates/yantrikdb-core/src/engine/storage.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/storage.rs)
- [crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)
# Five-Index Architecture
## Overview
The Five-Index Architecture is yantrikdb's multi-layered indexing system designed to support diverse query patterns across cognitive memory types. Each index layer specializes in a specific access pattern—vector similarity, temporal ordering, graph traversal, full-text search, and structured filtering—enabling the engine to retrieve relevant memories with minimal latency while maintaining consistency across the working set and persistent storage.
The architecture divides responsibility across five specialized index types:
| Index | Primary Role | Access Pattern |
|-------|--------------|----------------|
| **HNSW Index** | Vector similarity search | ANN queries on embeddings |
| **Delta Index** | Recent writes and updates | In-memory working set |
| **Graph Index** | Relationship traversal | Multi-hop graph queries |
| **Storage Index** | Persistent record management | CRUD operations with SQLite |
| **Recall Index** | Federated cross-index queries | Multi-dimensional recall |
资料来源：[crates/yantrikdb-core/src/engine/indices.rs:1-50]()
## Architecture Diagram
```mermaid
graph TB
subgraph "Query Interface"
Q[RecallQuery]
end
subgraph "Five Index Layers"
H[HNSW Index
Vector ANN]
D[Delta Index
Working Set]
G[Graph Index
Relationships]
S[Storage Index
Persistent SQLite]
R[Recall Index
Federated Router]
end
subgraph "Data Sources"
E[Embedding Cache]
M[Memory Nodes]
R2[Relational Tables]
end
Q --> R
R --> H
R --> D
R --> G
R --> S
H --> E
D --> M
G --> M
S --> R2
```
## HNSW Index Layer
### Purpose and Scope
The Hierarchical Navigable Small World (HNSW) index provides approximate nearest neighbor (ANN) search over high-dimensional embedding vectors. This layer powers semantic similarity queries, enabling the system to retrieve memories based on meaning rather than exact keyword matches.
资料来源：[crates/yantrikdb-core/src/vector/hnsw.rs:1-100]()
### Key Components
The HNSW implementation in yantrikdb supports the following configuration parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `m` | `u32` | 16 | Max connections per node |
| `ef_construction` | `u32` | 200 | Search width during build |
| `ef_search` | `u32` | 100 | Search width during query |
| `level_mult` | `f64` | 1/ln(M) | Level generation factor |
### Query Flow
```mermaid
sequenceDiagram
participant Q as Query
participant H as HNSW Layer
participant E as Embedding Cache
participant R as Results
Q->>H: RecallQuery with embedding
H->>H: Layer 0 scan
H->>H: Greedy search up layers
H->>E: Fetch top_k candidates
E-->>H: Candidate vectors
H->>H: Re-rank by distance
H-->>R: Ordered results
```
## Delta Index Layer
### Purpose and Scope
The Delta Index maintains a working set of recently inserted or updated records before they are flushed to persistent storage. This write buffer enables high-throughput ingestion while preserving query consistency for recent data.
资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs:1-100]()
### Write Path
When a new memory is created, the system:
1. Writes to the Delta Index immediately (low latency)
2. Appending to the HNSW structure if vector is present
3. Delaying SQLite flush until batch threshold
### Consistency Model
The Delta Index implements a hybrid consistency model:
- **Read-your-writes**: Queries against recent data include Delta entries
- **Staleness bound**: Configurable flush interval (default: 1 second)
- **Rollback support**: Unflushed entries can be discarded on abort
```mermaid
graph LR
A[Write Request] --> B{Delta Index
In-Memory}
B --> C{HNSW Update
Immediate}
C --> D[Query Path]
B -.->|Flush| E[Storage Index
SQLite]
E --> D
```
## Graph Index Layer
### Purpose and Scope
The Graph Index manages typed relationships between memory nodes, supporting complex multi-hop queries. Each edge type has associated metadata including activation transfer factors and temporal validity windows.
资料来源：[crates/yantrikdb-core/src/knowledge/graph.rs:1-100]()
资料来源：[crates/yantrikdb-core/src/knowledge/graph_index.rs:1-100]()
### Supported Edge Types
| Edge Type | Activation Transfer | Use Case |
|-----------|---------------------|----------|
| `causes` | 0.8 | Causal chains |
| `supports` | 0.7 | Supporting evidence |
| `triggers` | 0.7 | Event triggers |
| `advances_goal` | 0.6 | Goal progress |
| `requires` | 0.5 | Prerequisites |
| `subtask_of` | 0.4 | Hierarchical tasks |
| `predicts` | 0.4 | Predictive relations |
| `associated_with` | 0.3 | Weak associations |
| `similar_to` | 0.3 | Analogy detection |
| `instance_of` | 0.3 | Categorization |
| `part_of` | 0.3 | Containment |
| `precedes_temporally` | 0.2 | Temporal ordering |
| `contradicts` | -0.5 | Conflict detection |
| `blocks_goal` | -0.6 | Obstacle modeling |
| `prevents` | -0.7 | Prevention relations |
| `constrains` | -0.4 | Constraint edges |
### Graph Traversal API
```rust
// Core graph traversal via RecallQuery
RecallQuery::new(embedding)
.top_k(10)
.expand_entities(true)
.max_hops(3)
```
## Storage Index Layer
### Purpose and Scope
The Storage Index provides durable persistence for all memory records using SQLite. This layer handles transaction management, crash recovery, and long-term storage optimization.
资料来源：[crates/yantrikdb-core/src/engine/storage.rs:1-100]()
### Schema Overview
| Table | Primary Key | Indexes |
|-------|-------------|---------|
| `memories` | `rid` | `namespace`, `created_at`, `kind` |
| `edges` | `(src, rel_type, dst)` | `rel_type`, `src`, `dst` |
| `relation_policies` | `(relation_type, namespace)` | `namespace` |
### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `memory_type` | `Option<&str>` | Filter by node kind |
| `namespace` | `Option<&str>` | Filter by namespace |
| `time_window` | `Option<(f64, f64)>` | Temporal bounds |
| `domain` | `Option<&str>` | Domain classification |
| `source` | `Option<&str>` | Provenance filter |
## Recall Index Layer
### Purpose and Scope
The Recall Index acts as a federated query router that orchestrates multi-index searches. It combines results from HNSW, Delta, Graph, and Storage indices according to query parameters and relevance scoring.
### Query Pipeline
```mermaid
flowchart TD
A[RecallQuery] --> B[Parse Parameters]
B --> C{HNSW Index}
B --> D{Delta Index}
B --> E{Graph Index}
B --> F{Storage Index}
C --> G[Result Merge]
D --> G
E --> G
F --> G
G --> H[Re-rank by Score]
H --> I[Top-K Selection]
I --> J[Return Ordered Results]
```
### Query Construction
```rust
let q = RecallQuery::new(embedding)
.top_k(10)
.memory_type("episodic")
.namespace("work")
.time_window(start_ts, end_ts)
.expand_entities(true)
.include_consolidated(false);
```
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-80]()
## Index Synchronization
### Write Ordering
All index updates follow a strict ordering guarantee:
1. **Delta Index** receives write first (primary)
2. **HNSW Index** updated for vector-bearing records
3. **Graph Index** updated for edge-creating operations
4. **Storage Index** flush queued for background persistence
### Failure Recovery
| Failure Point | Recovery Action |
|---------------|-----------------|
| Delta write fails | Abort entire transaction |
| HNSW update fails | Mark record inconsistent, retry |
| Graph update fails | Rollback edge, alert |
| Storage flush fails | Retain in Delta, retry on restart |
## Performance Characteristics
| Operation | HNSW | Delta | Graph | Storage |
|-----------|------|-------|-------|---------|
| Point query | O(log n) | O(1) | O(1) | O(log n) |
| Range query | N/A | O(n) | O(n) | O(log n + k) |
| ANN search | O(ef × log n) | N/A | N/A | N/A |
| Traversal | N/A | N/A | O(m^h) | N/A |
| Write | O(log n) | O(1) | O(1) | O(log n) |
## Configuration
The Five-Index system is configured via `ThinkConfig`:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `importance_threshold` | 0.5 | Minimum relevance for surfacing |
| `decay_threshold` | 0.3 | Importance decay trigger |
| `max_triggers` | 10 | Concurrent trigger limit |
## Summary
The Five-Index Architecture enables yantrikdb to handle diverse cognitive memory workloads by specializing each index for its access pattern. The HNSW layer provides fast semantic search, Delta absorbs write bursts, Graph manages relationships, Storage ensures durability, and Recall federates queries across all layers. This design allows the system to balance latency, throughput, and consistency according to workload characteristics.
---
## Decoupled Write Path (LSM Architecture)
### 相关页面
相关主题：[Five-Index Architecture](#page-five-index-architecture), [Storage Engine](#page-storage-engine)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/decoupled_write_path_rfc.md](https://github.com/yantrikos/yantrikdb/blob/main/docs/decoupled_write_path_rfc.md)
- [CONCURRENCY.md](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md)
- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)
- [crates/yantrikdb-core/src/engine/materializer.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/materializer.rs)
# Decoupled Write Path (LSM Architecture)
## Overview
The Decoupled Write Path is the core write infrastructure of yantrikdb, implementing a Log-Structured Merge-tree (LSM) architecture that separates write operations from indexing and compaction. This design ensures high write throughput while maintaining read performance through asynchronous background compaction.
The architecture is built on the principle that write operations must be as fast as possible, deferring expensive vector indexing work to background processes. This decoupled approach prevents write operations from blocking on indexing operations, enabling the system to handle high concurrency workloads without regression.
资料来源：[CONCURRENCY.md]()
## Architecture Components
### DeltaIndex: The Write Buffer
The `DeltaIndex` is the primary write buffer in the LSM architecture. It provides lock-free append operations for new entries and tombstone operations for deletions.
```mermaid
graph TD
subgraph WritePath["Write Path"]
W[Write Request] --> DI[DeltaIndex]
DI --> |append| DE[DeltaEntry]
DE --> |O1 push| PendingVec[Pending Vec]
end
subgraph CompactionPath["Background Compaction"]
PendingVec --> |seal| CT[Cold Tier]
CT --> |clone-rebuild| NH[New HnswIndex]
NH --> |install| CurrentCold[Current Cold Tier]
end
subgraph ReadPath["Read Path"]
CurrentCold --> |ArcSwap| RR[Read Replicas]
end
```
**DeltaIndex Write Operations:**
| Operation | Complexity | Lock Type | Description |
|-----------|-----------|-----------|-------------|
| `append` | O(1) | `RwLock>` | Add new entry to pending buffer |
| `tombstone` | O(1) | `RwLock>` | Mark entry as deleted |
| `seal_delta_for_compaction` | O(1) | Brief lock hold | Swap pending entries for compaction |
| `compact` | O(n) rebuild | No foreground locks | Clone and rebuild cold tier |
资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs]()
### Two-Tier Storage Model
The storage model consists of two tiers:
1. **Hot Tier (DeltaIndex)**: Contains all recent writes and tombstones not yet compacted
2. **Cold Tier (HnswIndex)**: Immutable, compacted index containing historical data
```mermaid
graph LR
subgraph HotTier["Hot Tier - DeltaIndex"]
D1[DeltaEntry 1]
D2[DeltaEntry 2]
D3[DeltaEntry N]
end
subgraph ColdTier["Cold Tier - HnswIndex"]
H1[HnswIndex
immutable]
H2[HnswIndex
immutable]
end
HotTier --> |periodic| ColdTier
```
**Invariant:** The cold tier MUST use `ArcSwap` for lock-free reader access. Replacing with `RwLock` or `Mutex` causes read latency regression.
资料来源：[CONCURRENCY.md]()
## Concurrency Rules
The write path enforces strict concurrency rules to prevent deadlocks and ensure forward progress under high write load.
### Rule 1: Foreground Writes Must Be O(1)
All foreground write operations MUST only touch O(1) data structures:
| Allowed Operations | Forbidden Operations |
|-------------------|---------------------|
| `DeltaIndex::append` | `HnswIndex::insert` |
| `DeltaIndex::tombstone` | `HnswIndex::remove` |
| `assign_seq` (atomic fetch) | `compact()` |
| `bump_visible_seq` | Any non-O(1) lock acquisition |
资料来源：[CONCURRENCY.md]()
### Rule 2: Background Compaction Isolation
Background compaction MUST NOT share lock primitives with foreground writes:
```mermaid
sequenceDiagram
participant FW as Foreground Write
participant DI as DeltaIndex
participant CP as Compactor
participant HI as HnswIndex
FW->>DI: append(entry)
Note over DI: Brief RwLock write
O(1) push
CP->>DI: seal_delta_for_compaction()
Note over DI: Brief lock for seal
CP->>CP: clone cold + sealed entries
Note over CP: No locks held here
CP->>HI: ArcSwap new index
Note over HI: Brief lock for install
```
**Compactor Responsibilities:**
1. Call `seal_delta_for_compaction()` to get a stable snapshot
2. Perform HNSW rebuild off the hot path
3. Install new cold tier via `ArcSwap`
资料来源：[CONCURRENCY.md]()
### Rule 3: Visible Sequence Tracking
The `visible_seq` map tracks the minimum sequence number visible to readers per namespace, enabling read-your-writes (RYW) semantics.
```rust
// Type: DashMap
visible_seq: DashMap
// Fast path reads (lock-free)
get(ns).map(|e| e.load(Acquire))
// Fast path writes
get(ns).fetch_max(seq, Release)
```
| Property | Value |
|----------|-------|
| Data Structure | `dashmap::DashMap` |
| Read Path | Lock-free via `AtomicU64::load(Acquire)` |
| Write Path | Lock-free via `AtomicU64::fetch_max(Release)` |
| Scope | Per-namespace |
资料来源：[CONCURRENCY.md]()
## Write Operations
### Standard Write Flow
```mermaid
graph TD
Start[Write Request] --> Validate{Validate}
Validate --> |valid| Seq[assign_seq]
Validate --> |invalid| Reject[Reject]
Seq --> SQL[SQL SAVEPOINT]
SQL --> Delta[DeltaIndex::append]
Delta --> Bump[bump_visible_seq]
Bump --> Commit[Commit Transaction]
Commit --> Done[Return to Client]
Reject --> Fail[Return Error]
```
### Record With RID Pattern
All write operations follow the `record_with_rid` pattern:
```rust
// Pattern for all write primitives
fn write_operation(&self, ...) -> Result {
// 1. SQL with SAVEPOINT for rollback
let rid = sql_transaction(|| {
// 2. Append to DeltaIndex (O(1) push)
self.delta_index.append(entry)?;
Ok(assigned_rid)
})?;
// 3. Bump visible sequence
self.bump_visible_seq(namespace, seq)?;
Ok(rid)
}
```
资料来源：[CONCURRENCY.md]()
### Sequence Number Assignment
The `assign_seq` function uses atomic operations for lock-free sequence generation:
```rust
// Atomic fetch_add or fetch_max
let seq = self
.seq_counter
.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
```
This ensures each write receives a unique, monotonically increasing sequence number without contention.
## Compaction Process
### Compaction Lifecycle
```mermaid
graph LR
subgraph Phase1["Phase 1: Seal"]
A[Active Delta] --> B[Seal Delta]
B --> C[Frozen Snapshot]
end
subgraph Phase2["Phase 2: Rebuild"]
C --> D[Clone Cold Hnsw]
D --> E[Merge Sealed Entries]
E --> F[Build New Hnsw]
end
subgraph Phase3["Phase 3: Install"]
F --> G[ArcSwap Install]
G --> H[New Current Cold]
end
```
### Compaction Rules
| Rule | Description |
|------|-------------|
| Lock Isolation | Compactor holds `delta` RwLock only for seal and install |
| No Hot Locks | Between seal and install, NO locks shared with foreground |
| ArcSwap | Cold tier replacement uses atomic pointer swap |
| Snapshot | `seal_delta_for_compaction()` returns stable Arc snapshot |
资料来源：[CONCURRENCY.md]()
### Compaction Triggers
The system triggers compaction based on configurable policies:
| Trigger Type | Default Cooldown | Default Expiry |
|-------------|-----------------|----------------|
| DecayReview | 3 days | 7 days |
| ConsolidationReady | 1 day | 3 days |
| ConflictEscalation | 2 days | 14 days |
| Redundancy | 1 day | 7 days |
| PatternDiscovered | 7 days | 7 days |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
## Read-Your-Writes Semantics
### Recall With Sequence
The `recall_with_seq` method enables clients to wait for their writes to become visible:
```rust
pub fn recall_with_seq(
&self,
query_embedding: &[f32],
top_k: usize,
min_seq: u64, // Sequence from write operation
namespace: Option<&str>,
timeout: Duration,
) -> Result> {
let ns = namespace.unwrap_or("default");
// Wait for visible_seq to reach min_seq
self.wait_for_visible_seq(ns, min_seq, timeout)?;
// Safe to recall - all writes up to min_seq are visible
self.recall(query_embedding, top_k, ...)
}
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `min_seq` | `u64` | Minimum sequence number client observed |
| `namespace` | `Option<&str>` | Target namespace (required for correct RYW) |
| `timeout` | `Duration` | Maximum wait time |
资料来源：[crates/yantrikdb-core/src/engine/recall.rs]()
### Visible Sequence Wait
```mermaid
sequenceDiagram
participant C as Client
participant VS as VisibleSeq Map
participant REC as Recall Engine
C->>VS: load current seq for namespace
Note over VS: AtomicU64 load
VS-->>C: current_seq
alt current_seq < min_seq
C->>C: wait_for_visible_seq()
loop until visible or timeout
C->>VS: load current seq
VS-->>C: current_seq
end
end
C->>REC: recall(...)
REC-->>C: Results (guaranteed visible)
```
## Materializer Integration
The materializer component coordinates between the write path and the cognitive layer, processing update operations extracted from natural language input.
```mermaid
graph TD
subgraph Input["Input Processing"]
NL[Natural Language] --> EX[Extractor]
EX --> OT[Operation Templates]
end
subgraph Write["Write Path"]
OT --> UW[UpdateOps]
UW --> DI[DeltaIndex]
DI --> SEQ[Sequence Assignment]
SEQ --> VS[VisibleSeq Update]
end
subgraph Cognitive["Cognitive Layer"]
VS --> MAT[Materializer]
MAT --> ST[State Update]
ST --> GP[Graph Propagation]
end
```
资料来源：[crates/yantrikdb-core/src/engine/materializer.rs]()
资料来源：[crates/yantrikdb-core/src/cognition/extractor.rs]()
## Configuration
### ThinkConfig Parameters
The cognition loop configuration affects compaction behavior:
| Parameter | Description | Impact |
|-----------|-------------|--------|
| `importance_threshold` | Minimum importance for processing | Filters low-value nodes |
| `decay_threshold` | Decay rate trigger | Affects when entries move to cold |
| `max_triggers` | Maximum triggers per cycle | Limits resource usage |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
### Memory Query Options
The Python bindings expose configuration for recall operations:
```rust
#[pyo3(signature = (
query=None, embedding=None, top_k=10, memory_type=None, namespace=None,
time_window=None, expand_entities=false, include_consolidated=false,
skip_reinforce=false, domain=None, source=None
))]
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `Option<&str>` | `None` | Text query for semantic search |
| `embedding` | `Option>` | `None` | Pre-computed embedding vector |
| `top_k` | `usize` | `10` | Number of results to return |
| `memory_type` | `Option<&str>` | `None` | Filter by memory type |
| `namespace` | `Option<&str>` | `None` | Target namespace |
| `include_consolidated` | `bool` | `false` | Include cold tier results |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs]()
## Performance Characteristics
### Write Path Guarantees
| Metric | Guarantee |
|--------|-----------|
| Write Latency | O(1) for DeltaIndex append |
| Contention | Lock-free sequence assignment |
| Durability | SQL SAVEPOINT + DeltaIndex |
| Visibility | Guaranteed via visible_seq |
### Compaction Guarantees
| Metric | Guarantee |
|--------|-----------|
| Lock Duration | O(1) for seal and install |
| Hot Path Impact | Zero locks during rebuild |
| Reader Impact | ArcSwap provides instant switch |
| Memory | Clone-on-write for cold tier |
### Read Path Guarantees
| Metric | Guarantee |
|--------|-----------|
| Read Latency | Lock-free via ArcSwap cold tier |
| Consistency | Read-your-writes via visible_seq |
| Namespace Isolation | Per-namespace sequence tracking |
## Error Handling
### Conflict Resolution
The system tracks conflicts between memories for resolution:
```rust
pub struct Conflict {
pub conflict_id: String,
pub conflict_type: String, // identity_fact, preference, temporal
pub priority: String, // critical, high, medium, low
pub memory_a: String,
pub memory_b: String,
pub entity: Option,
pub detected_at: f64,
pub resolution_note: Option,
}
```
| Conflict Type | Default Priority |
|--------------|------------------|
| IdentityFact | critical |
| Preference | high |
| Temporal | high |
| Consolidation | medium |
| Minor | low |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
## Related Documentation
- [Concurrency Rules](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md) - Detailed concurrency invariants
- [Decoupled Write Path RFC](https://github.com/yantrikos/yantrikdb/blob/main/docs/decoupled_write_path_rfc.md) - Design rationale
- [DeltaIndex Implementation](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs) - Source code
- [Materializer](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/materializer.rs) - Write coordination
---
## Storage Engine
### 相关页面
相关主题：[Five-Index Architecture](#page-five-index-architecture), [Decoupled Write Path (LSM Architecture)](#page-decoupled-write-path)
Relevant Source Files
The following source files were used to generate this documentation:
- [crates/yantrikdb-core/src/engine/lifecycle.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/lifecycle.rs)
- [crates/yantrikdb-core/src/engine/stats.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/stats.rs)
- [crates/yantrikdb-core/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)
- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)
- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)
# Storage Engine
## Overview
The YantrikDB Storage Engine is the core persistence layer responsible for storing, retrieving, and managing memory data in the SQLite database. It handles encrypted text storage, metadata management, storage tier organization, and integrates with the materialization subsystem for asynchronous processing of memory operations.
The storage engine operates as part of the broader engine module and maintains close integration with:
- The **Record System** for writing memories
- The **Recall System** for querying memories
- The **Materialization Pipeline** for asynchronous operation processing
- The **Encryption Layer** for secure text storage
## Core Data Models
### Memory Structure
The central data structure managed by the storage engine is the `Memory` struct, which encapsulates all attributes of a stored memory:
```rust
pub struct Memory {
pub rid: String, // Unique record identifier
pub memory_type: String, // episodic, semantic, procedural, etc.
pub text: String, // Decrypted memory content
pub created_at: f64, // Creation timestamp
pub importance: f64, // Importance score [0.0, 1.0]
pub valence: f64, // Emotional valence [-1.0, 1.0]
pub half_life: f64, // Decay half-life in seconds
pub last_access: f64, // Last access timestamp
pub access_count: u32, // Number of times accessed
pub consolidation_status: String, // Current consolidation state
pub storage_tier: String, // hot, warm, cold, frozen
pub consolidated_into: Option,// RID of consolidated memory
pub metadata: serde_json::Value, // Encrypted JSON metadata
pub namespace: String, // Logical namespace partition
pub certainty: f64, // Belief certainty [0.0, 1.0]
pub domain: String, // Domain classification
pub source: String, // Provenance source type
pub emotional_state: Option, // Associated emotional context
pub session_id: Option, // Session identifier
pub due_at: Option, // Due timestamp for tasks
pub temporal_kind: Option, // Temporal classification
}
```
资料来源：[engine/lifecycle.rs:200-225]()
### Storage Tiers
YantrikDB implements a tiered storage architecture to optimize memory access patterns:
| Tier | Purpose | Access Pattern |
|------|---------|----------------|
| `hot` | Frequently accessed memories | In-memory cache priority |
| `warm` | Regular operational memories | Standard retrieval |
| `cold` | Archival memories | Lazy loading |
| `frozen` | Long-term storage | Minimal access |
资料来源：[engine/lifecycle.rs:214]()
### Consolidation Status
Memories maintain a consolidation status indicating their state in the memory consolidation lifecycle:
| Status | Description |
|--------|-------------|
| `observed` | Raw observation, no consolidation |
| `inferred` | Pattern-based inference |
| `told` | Explicitly stated by user |
| `experimented` | Confirmed via experiment |
| `extracted` | Extracted from external documents |
| `consolidated` | Merged from multiple sources |
| `system_default` | System-provided default |
Each status carries a reliability prior that affects belief revision:
```rust
pub fn reliability_prior(self) -> f64 {
match self {
Self::Told => 0.95, // User explicitly stated
Self::Observed => 0.90, // Directly observed
Self::Experimented => 0.85, // Controlled experiment
Self::Extracted => 0.75, // External documents
Self::Inferred => 0.60, // Pattern inference
Self::Consolidated => 0.80, // Multi-source merge
Self::SystemDefault => 0.50, // Defaults
}
}
```
资料来源：[cognition/state.rs:180-192]()
## Storage Architecture
### High-Level Architecture
```mermaid
graph TD
subgraph "Python API Layer"
PYM[py_engine/memory.rs]
end
subgraph "Engine Core"
REC[Record System]
RCL[Recall System]
MAT[Materialization Pipeline]
end
subgraph "Storage Layer"
ENG[Engine Instance]
SQL[(SQLite Database)]
CRE[Encryption Layer]
end
PYM --> REC
PYM --> RCL
REC --> ENG
REC --> MAT
MAT --> ENG
ENG --> SQL
ENG --> CRE
CRE --> SQL
```
### Encryption Integration
Text fields are encrypted before storage and decrypted on retrieval to ensure data privacy:
```rust
let text = self.decrypt_text(&row.2)?;
let meta_str = self.decrypt_text(&row.12)?;
let metadata: serde_json::Value = serde_json::from_str(&meta_str)
.unwrap_or(serde_json::Value::Object(Default::default()));
```
资料来源：[engine/lifecycle.rs:210-214]()
## Record Operations
### Recording a Memory
The storage engine provides the `record()` method for storing new memories with automatic embedding:
```rust
db.record(
text, // Memory content
memory_type, // episodic, semantic, etc.
importance, // Importance score
valence, // Emotional valence
half_life, // Decay half-life
&meta, // JSON metadata
&emb, // Embedding vector
namespace, // Logical partition
certainty, // Belief certainty
domain, // Domain classification
source, // Provenance source
emotional_state, // Emotional context
)
```
资料来源：[py_engine/memory.rs:45-60]()
### Python Bindings
The Python API exposes record functionality through `py_engine/memory.rs`:
```python
# Record a memory with auto-embedding
db.record(
text="Meeting with John at 3pm",
memory_type="episodic",
namespace="work",
importance=0.8,
valence=0.5,
)
```
The `record()` method accepts these parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | `str` | Yes | Memory content |
| `embedding` | `Vec` | No | Pre-computed embedding (auto-generated if None) |
| `memory_type` | `str` | No | Type classification |
| `namespace` | `str` | No | Logical partition |
| `importance` | `float` | No | Importance score (0.0-1.0) |
| `valence` | `float` | No | Emotional valence (-1.0 to 1.0) |
| `half_life` | `float` | No | Decay half-life in seconds |
| `metadata` | `dict` | No | Additional JSON metadata |
| `certainty` | `float` | No | Belief certainty |
| `domain` | `str` | No | Domain classification |
| `source` | `str` | No | Provenance source |
| `emotional_state` | `str` | No | Emotional context |
资料来源：[py_engine/memory.rs:30-60]()
## Recall Operations
### Querying Memories
The recall system retrieves memories based on embedding similarity and filters:
```rust
db.recall(
&emb, // Query embedding
top_k, // Number of results
time_window, // Optional time filter
memory_type, // Type filter
include_consolidated, // Include consolidated memories
expand_entities, // Expand entity references
query, // Optional text query
skip_reinforce, // Skip reinforcement learning
namespace, // Namespace filter
domain, // Domain filter
source, // Source filter
)
```
资料来源：[py_engine/memory.rs:105-120]()
### Recall Query Builder
The `RecallQuery` struct provides a fluent interface for building recall queries:
```rust
let mut q = yantrikdb_core::RecallQuery::new(emb).top_k(top_k);
if let Some(mt) = memory_type {
q = q.memory_type(mt);
}
if let Some(ns) = namespace {
q = q.namespace(ns);
}
if let Some(tw) = time_window {
q = q.time_window(tw.0, tw.1);
}
```
资料来源：[py_engine/memory.rs:145-155]()
### Recall Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `Option<&str>` | `None` | Text query |
| `query_embedding` | `Option>` | `None` | Pre-computed embedding |
| `top_k` | `usize` | `10` | Number of results |
| `time_window` | `Option<(f64, f64)>` | `None` | Time range filter |
| `memory_type` | `Option<&str>` | `None` | Memory type filter |
| `include_consolidated` | `bool` | `false` | Include consolidated |
| `expand_entities` | `bool` | `true` | Expand entity references |
| `skip_reinforce` | `bool` | `false` | Skip reinforcement |
| `namespace` | `Option<&str>` | `None` | Namespace filter |
| `domain` | `Option<&str>` | `None` | Domain filter |
| `source` | `Option<&str>` | `None` | Source filter |
资料来源：[py_engine/memory.rs:65-80]()
## Materialization Pipeline
### Overview
The materialization pipeline handles asynchronous processing of memory operations to ensure durability and consistency. It operates in phases:
```mermaid
graph LR
A[Write Ops] --> B[Phase 3: Record/Rollback]
B --> C[Phase 4.1: Materialize Pending]
C --> D[Phase 4.2: Apply Updates]
D --> E[Phase 4.3: Post-Record Materialization]
E --> F[Applied]
```
### Phase 3: Record Materialization
Handles synchronous recording of operations with rollback capability:
```rust
"record" | "forget" | "relate" | "correct" | "consolidate" => {
tracing::trace!(
target: "yantrikdb::ingest::materialize",
op_id = %op_id,
op_type = %op_type,
"phase 3 stub: marking pending op as applied without inline materialization"
);
if self.mark_op_applied(op_id)? {
applied += 1;
}
}
```
资料来源：[engine/stats.rs:95-105]()
### Phase 4.1-4.2: Update Operations
For update operations like task completion and status changes:
```rust
"create_task" | "update_task_status" | "create_goal" | "update_goal"
| "record_belief" | "relate_belief" | "update_preference"
| "record_need" | "record_emotion" => {
// Attempt materialization
match materialize_fn(payload) {
Ok(()) => {
if self.mark_op_applied(op_id)? {
applied += 1;
}
}
Err(e) => {
tracing::warn!(
target: "yantrikdb::ingest::materialize",
op_id = %op_id,
error = %e,
"post-record-with-rid materialization failed; leaving pending for retry"
);
}
}
}
```
资料来源：[engine/stats.rs:70-90]()
### Phase 4.3: Post-Record Materialization
Handles entity and relation extraction that runs on the materializer thread to avoid blocking the foreground caller:
> Mirrors the post-INSERT entity/relation extraction loop that used to live on the foreground `record()` path. Now runs on the materializer thread so the foreground caller is not blocked on the unbounded loop count.
资料来源：[engine/stats.rs:130-135]()
## Conflict Detection
The storage engine integrates with the conflict detection system for distributed scenarios:
```rust
// Phase 2: Evaluate each candidate pair with policy awareness
for (src, rel_type, dst1, dst2, vf1, vt1, vf2, vt2, namespace) in &candidates {
if conflicts.len() >= max_conflicts {
break;
}
// RFC 006 Phase 3: check relation policy before flagging
let policy: Option<(bool, bool, String)> = {
let conn = db.conn();
conn.query_row(
"SELECT overlap_allowed, temporal_required, missing_time_severity \
FROM relation_policies \
WHERE relation_type = ?1 AND (namespace = ?2 OR namespace = '*') \
ORDER BY CASE WHEN namespace = ?2 THEN 0 ELSE 1 END \
LIMIT 1",
params![rel_type, namespace],
|row| { ... }
)
};
}
```
资料来源：[distributed/conflict.rs:85-105]()
### Conflict Types
| Type | Priority | Description |
|------|----------|-------------|
| `identity_fact` | Critical | Contradiction in core facts |
| `preference` | High | Preference conflict |
| `temporal` | High | Time-based conflict |
| `consolidation` | Medium | Consolidation conflict |
| `minor` | Low | Minor inconsistency |
资料来源：[base/types.rs:50-60]()
## Retrieval by ID
The `get_memory_by_rid()` method retrieves a specific memory by its record ID:
```rust
pub fn get_memory_by_rid(&self, rid: &str) -> Result> {
let result = conn.query_row(
"SELECT rid, memory_type, text, created_at, importance, valence,
half_life, last_access, access_count, consolidation_status,
storage_tier, consolidated_into, metadata, namespace,
certainty, domain, source, emotional_state, session_id,
due_at, temporal_kind
FROM memories WHERE rid = ?1",
params![rid],
|row| Ok((...)) // 21 columns mapped
)?;
// Decrypt and deserialize
let text = self.decrypt_text(&row.2)?;
let meta_str = self.decrypt_text(&row.12)?;
let metadata: serde_json::Value = serde_json::from_str(&meta_str)?;
Ok(Some(Memory { ... }))
}
```
资料来源：[engine/lifecycle.rs:195-225]()
## Query Interface
The storage engine provides a flexible query interface combining text and embedding search:
```python
# Query memories with combined text and embedding search
results = db.query(
query="team meeting",
embedding=None, # Auto-generate from query
top_k=10,
memory_type="episodic",
namespace="work",
time_window=(start_ts, end_ts),
expand_entities=True,
include_consolidated=False,
)
```
资料来源：[py_engine/memory.rs:85-100]()
### Query vs Recall
| Aspect | `query()` | `recall()` |
|--------|-----------|------------|
| Purpose | Combined text + embedding search | Pure embedding similarity |
| Use Case | Exploratory queries | Memory association |
| Parameters | Query text or embedding | Primarily embedding |
| Filters | Full filter suite | Full filter suite |
## Error Handling
The storage engine uses Rust's `Result` type for error handling with the following patterns:
```rust
.ok_or_else(|| PyRuntimeError::new_err("YantrikDB is closed"))
```
Errors are propagated through the Python bindings using the `map_err` function which converts Rust errors to Python exceptions.
资料来源：[py_engine/memory.rs:40]()
## Performance Considerations
### Memory Retrieval Optimization
1. **Encryption on-demand**: Text fields are only decrypted when accessed
2. **Lazy metadata parsing**: JSON metadata is parsed only when needed
3. **Storage tiering**: Frequently accessed memories can be promoted to hot tier
4. **Consolidation filtering**: `include_consolidated=false` skips consolidation lookups
### Asynchronous Materialization
Post-record operations run on a background materializer thread to prevent foreground blocking:
> Now runs on the materializer thread so the foreground caller is not blocked on the unbounded loop count (5-15...)
资料来源：[engine/stats.rs:135-138]()
## Related Systems
| System | Integration Point | Purpose |
|--------|-------------------|---------|
| Record System | `record()` | Memory creation |
| Recall System | `recall()`, `query()` | Memory retrieval |
| Materialization | `materialize_ops()` | Async operation processing |
| Conflict Detection | `relation_policies` table | Distributed consistency |
| Encryption | `decrypt_text()` | Data security |
## API Reference Summary
### Core Methods
| Method | File | Purpose |
|--------|------|---------|
| `record()` | py_engine/memory.rs | Store new memory |
| `recall()` | py_engine/memory.rs | Retrieve by embedding |
| `query()` | py_engine/memory.rs | Combined search |
| `get_memory_by_rid()` | engine/lifecycle.rs | Lookup by ID |
| `materialize_ops()` | engine/stats.rs | Process pending ops |
### Data Structures
| Struct | File | Purpose |
|--------|------|---------|
| `Memory` | engine/lifecycle.rs | Core memory representation |
| `RecallQuery` | py_engine/memory.rs | Query builder |
| `Conflict` | base/types.rs | Conflict representation |
---
## Core API Reference
### 相关页面
相关主题：[Overview](#page-overview), [Cognition Layer](#page-cognition-layer), [Conflict Detection and Resolution](#page-conflict-resolution)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-core/src/engine/mod.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/mod.rs)
- [crates/yantrikdb-core/src/engine/record.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/record.rs)
- [crates/yantrikdb-core/src/engine/recall.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/recall.rs)
- [crates/yantrikdb-core/src/engine/graph_ops.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/graph_ops.rs)
- [crates/yantrikdb-core/src/base/scoring.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/scoring.rs)
# Core API Reference
This page documents the core engine API of yantrikdb, covering the fundamental operations for memory storage, retrieval, graph relationships, and cognitive processing.
## Overview
The Core API provides the foundational primitives for building personal memory systems. It consists of four primary subsystems:
| Subsystem | Purpose |
|-----------|---------|
| **Record** | Store memories with importance, valence, and metadata |
| **Recall** | Semantic search and retrieval using embeddings |
| **Graph** | Relationship management between memory nodes |
| **Cognitive** | Higher-order reasoning (think loop, conflict detection) |
资料来源：[crates/yantrikdb-core/src/engine/mod.rs]()
### Architecture Overview
```mermaid
graph TD
A[User Input] --> B[Record API]
A --> C[Recall API]
A --> D[Graph API]
B --> E[(SQLite Storage)]
C --> E
D --> E
E --> F[Cognitive Engine]
F --> G[Think Loop]
G --> H[Consolidation]
G --> I[Conflict Detection]
G --> J[Pattern Mining]
```
## Memory Data Model
### Core Memory Structure
The fundamental unit of storage in yantrikdb is the `Memory` struct, defined in `lifecycle.rs`:
| Field | Type | Description |
|-------|------|-------------|
| `rid` | `String` | Unique resource identifier |
| `memory_type` | `String` | Type classification (episodic, semantic, procedural) |
| `text` | `String` | The actual memory content (encrypted at rest) |
| `created_at` | `f64` | Unix timestamp of creation |
| `importance` | `f64` | Significance score [0.0, 1.0] |
| `valence` | `f64` | Emotional valence [-
Error with Openai API: output new_sensitive (1027)
Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.
---
## Cognition Layer
### 相关页面
相关主题：[Core API Reference](#page-core-api), [Conflict Detection and Resolution](#page-conflict-resolution)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)
- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)
- [crates/yantrikdb-core/src/cognition/narrative.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/narrative.rs)
- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)
- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)
- [crates/yantrikdb-core/src/cognition/extractor.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/extractor.rs)
- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)
# Cognition Layer
The Cognition Layer is the reasoning and knowledge management subsystem of yantrikdb. It provides cognitive operations for belief revision, goal planning, intent recognition, pattern detection, and proactive user assistance. The layer orchestrates a pipeline of cognitive operators that process user interactions, external observations, and system events to maintain a dynamic model of user needs, goals, and preferences.
## Architecture Overview
The Cognition Layer operates as a staged pipeline that transforms raw observations into structured cognitive entities (beliefs, goals, tasks, routines, intents) and surfaces actionable insights to the user at appropriate moments.
```mermaid
graph TD
subgraph Input
Obs[User Observation] --> Extr[Extractor]
Ev[Evidence Input] --> Extr
end
subgraph "Cognitive Pipeline"
Extr --> Ops[Operator Pipeline]
Ops --> Attend[Attend]
Ops --> Recall[Recall]
Ops --> Believe[Believe]
Ops --> Compare[Compare]
Ops --> Plan[Plan]
Ops --> Project[Project]
Ops --> Anticipate[Anticipate]
Ops --> Assess[Assess]
Ops --> Coherence[Coherence Check]
end
subgraph "Working Memory"
Attend --> WS[Working Set]
Recall --> WS
end
subgraph "Long-term Store"
WS <--> KG[Knowledge Graph]
KG --> Beliefs[Beliefs]
KG --> Goals[Goals]
KG --> Routines[Routines]
end
subgraph "Output"
Coherence --> Surf[Surfacing]
Surf --> Suggest[Proactive Suggestion]
Surf --> SurfaceMode[Surface Modes]
end
```
## Node Types
The Cognition Layer manages a graph of cognitive nodes, each representing a distinct aspect of user state and knowledge.
### NodeKind Classification
| Kind | Description | Persistence | Typical Confidence | Typical Activation |
|------|-------------|-------------|-------------------|-------------------|
| Entity | Real-world objects, people, concepts | Yes | 0.70 | 0.70 |
| Episode | Past experiences and events | Yes | 0.70 | 0.60 |
| Belief | User's mental models and facts | Yes | 0.70 | 0.70 |
| Goal | Desired outcomes | Yes | 0.85 | 0.75 |
| Task | Concrete action items | Yes | 0.90 | 0.80 |
| IntentHypothesis | Inferred user wants (transient) | No | 0.60 | 0.50 |
| Routine | Recurring behavioral patterns | Yes | 0.70 | 0.50 |
| Need | User requirements (Maslow-based) | Yes | 0.60 | 0.70 |
| Opportunity | Time-bounded chances for action | Yes | 0.40 | 0.60 |
| Risk | Potential problems | Yes | 0.40 | 0.70 |
| Constraint | Boundaries and rules | Yes | 0.90 | 0.80 |
| Preference | User choices and inclinations | Yes | 0.60 | 0.50 |
| ConversationThread | Dialogue context (transient) | No | 0.90 | 0.80 |
| ActionSchema | Reusable action templates | Yes | 0.70 | 0.40 |
资料来源：[state.rs:350-370](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
### Cognitive Attributes
Every cognitive node carries a universal attribute set defining its dynamic state:
| Attribute | Range | Description |
|-----------|-------|-------------|
| confidence | [0.0, 1.0] | Trust level in the node's accuracy |
| activation | [0.0, 1.0] | Current spreading activation energy |
| salience | [0.0, 1.0] | Prominence in user's attention |
| persistence | [0.0, 1.0] | How long this node stays relevant |
| valence | [-1.0, 1.0] | Emotional tone (negative to positive) |
| urgency | [0.0, 1.0] | Time-critical nature |
| novelty | [0.0, 1.0] | How surprising/unexpected (decays with repetition) |
| volatility | [0.0, 1.0] | Rate of attribute change |
| evidence_count | u32 | Number of supporting observations |
| provenance | ProvenanceType | Source reliability of this node |
资料来源：[state.rs:280-330](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Provenance System
The provenance system tracks the source and reliability of cognitive nodes, enabling appropriate trust calibration during reasoning.
### Provenance Types
| Type | Reliability Prior | Description |
|------|------------------|-------------|
| Told | 0.95 | User explicitly stated |
| Observed | 0.90 | Directly observed behavior |
| Experimented | 0.85 | Confirmed via controlled experiment |
| Consolidated | 0.80 | Merged from multiple sources |
| Extracted | 0.75 | From external documents |
| Inferred | 0.60 | Pattern-based inference |
| SystemDefault | 0.50 | Default values (weakest) |
资料来源：[state.rs:220-240](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Edge Types and Activation Spreading
Relationships between cognitive nodes are represented as typed edges with associated activation transfer coefficients that govern spreading activation dynamics.
| Edge Type | Transfer | Description |
|-----------|----------|-------------|
| Causes | 0.8 | Strong causal relationship |
| Supports | 0.7 | Confirms or strengthens target |
| Triggers | 0.7 | Initiates target activation |
| AdvancesGoal | 0.6 | Progresses toward goal |
| Requires | 0.5 | Prerequisite relationship |
| Predicts | 0.4 | Anticipatory relationship |
| SubtaskOf | 0.4 | Decomposition hierarchy |
| AssociatedWith | 0.3 | Weak contextual link |
| SimilarTo | 0.3 | Analogy relationship |
| InstanceOf | 0.3 | Classification relationship |
| PartOf | 0.3 | Compositional relationship |
| Prefers | 0.3 | Preference indicator |
| PrecedesTemporally | 0.2 | Temporal ordering |
| Contradicts | -0.4 | Mutual exclusion |
| Prevents | -0.6 | Active blocking |
| BlocksGoal | -0.7 | Prevents goal achievement |
| Avoids | -0.5 | Negative preference |
| Constrains | -0.5 | Imposes limitation |
资料来源：[state.rs:150-180](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Cognitive Operators
The reasoning pipeline executes a sequence of cognitive operators in priority order. Each operator performs a specific reasoning function.
### Operator Priorities
| Operator | Priority | Rationale |
|----------|----------|-----------|
| Attend | 10 | Foundation — always run |
| Recall | 9 | Critical for context |
| Believe | 8 | Evidence integration |
| Compare | 7 | Action selection |
| Constrain | 7 | Safety — always run if comparing |
| Plan | 6 | Means-ends reasoning |
| Project | 5 | Forward simulation |
| Anticipate | 4 | Proactive — nice to have |
| Assess | 3 | Meta — can skip under pressure |
| CoherenceCheck | 2 | Maintenance — skip if budget tight |
资料来源：[query_dsl.rs:40-55](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)
### Attend Operator
The Attend operator focuses attention on seed nodes and propagates activation through the knowledge graph.
```rust
pub struct AttendOp {
pub seeds: Vec, // Starting nodes for activation
pub max_hops: u32, // Maximum propagation depth
pub decay: f64, // Activation decay per hop
}
```
资料来源：[query_dsl.rs:65-70](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)
**Execution behavior:**
- Seeds receive a +0.3 activation boost (capped at 1.0)
- Activation spreads through edges with configurable decay
- Returns count of activated nodes and top-activated node list
资料来源：[engine/query_dsl.rs:180-210](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)
### Recall Operator
The Recall operator retrieves relevant memories from long-term storage into the working set.
```rust
pub struct RecallOp {
pub top_k: usize, // Maximum results
pub query: Option, // Text query
pub domain: Option, // Filter by domain
}
```
### Believe Operator
The Believe operator integrates new evidence into the belief system using Bayesian revision.
```rust
pub struct BelieveOp {
pub evidence: EvidenceInput, // New observation to integrate
}
pub struct EvidenceInput {
pub target: Option, // Target belief or create new
pub observation: String, // The evidence
pub direction: f64, // +1 = confirming, -1 = contradicting
}
```
### Compare Operator
Compares candidate actions or beliefs against constraints and preferences to select optimal choices.
### Plan Operator
Executes means-ends reasoning to generate action sequences that advance specified goals.
### Project Operator
Performs forward simulation to predict outcomes of potential action sequences.
### Anticipate Operator
Identifies opportunities and risks based on current state and detected patterns.
### Assess Operator
Evaluates overall system health, belief consistency, and goal progress.
### Coherence Check
Validates logical consistency across beliefs and detects conflicting information.
## User State Modeling
### Activity Type
The system tracks the user's current activity level to calibrate interruption costs and suggestion timing.
| Activity | Interruption Cost | Description |
|----------|------------------|-------------|
| Idle | 0.10 | No active task |
| JustReturned | 0.30 | Recently resumed work |
| Browsing | 0.35 | Passive consumption |
| Communicating | 0.45 | In conversation |
| TaskSwitching | 0.55 | Mid-task context switch |
| FocusedWork | 0.75 | Concentration mode |
| DeepFocus | 0.95 | Immersive concentration |
资料来源：[receptivity.rs:25-50](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)
### Need Categories
User needs are classified according to a needs-based taxonomy:
| Category | Description |
|----------|-------------|
| Informational | Knowledge and learning needs |
| Social | Connection and relationship needs |
| Emotional | Wellbeing and mood management |
| Organizational | Structure and order needs |
| Creative | Expression and innovation |
| Health | Physical wellbeing |
| Financial | Economic security |
| Professional | Career and productivity |
资料来源：[state.rs:10-25](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Action Types
Cognitive agents can perform actions of different kinds, each with associated base costs:
| Action | Base Cost | Description |
|--------|-----------|-------------|
| Abstain | 0.00 | Do nothing |
| Inform | 0.05 | Passive information delivery |
| Organize | 0.10 | Structure and categorization |
| Suggest | 0.15 | Propose without commitment |
| Communicate | 0.20 | Direct user interaction |
| Schedule | 0.25 | Time management |
| Warn | 0.30 | Alert about risks |
| Execute | 0.40 | Take automated action |
资料来源：[state.rs:100-130](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Task Lifecycle
Tasks move through a defined status workflow:
```mermaid
graph LR
P[Pending] --> IP[InProgress]
IP --> C[Completed]
IP --> B[Blocked]
P --> CAN[Cancelled]
B --> IP
CAN --> P
```
### Task Status
| Status | String Value | Description |
|--------|--------------|-------------|
| Pending | pending | Not yet started |
| InProgress | in_progress | Currently being worked |
| Completed | completed | Successfully finished |
| Cancelled | cancelled | Abandoned without completion |
| Blocked | blocked | Waiting on prerequisites |
资料来源：[state.rs:200-230](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
## Surfacing System
The surfacing system determines when and how to present proactive suggestions to the user.
### Surface Modes
| Mode | Description |
|------|-------------|
| Immediate | Show right now |
| Soon | Show within current context |
| Queued | Add to notification queue |
| Background | Process but don't interrupt |
### Suppression Reasons
Suggestions may be suppressed for various reasons:
| Reason | Description |
|--------|-------------|
| LowReceptivity | User is busy |
| ItemSuppressionRule | User preference to hide |
| QuietHours | Outside allowed hours |
| RateLimited | Too frequent |
| AntiNag | Already dismissed |
| MaxSurfaces | Budget exhausted |
| TooSoon | Recently surfaced |
| NotificationModeBlock | DND enabled |
资料来源：[surfacing.rs:15-30](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)
### ProactiveSuggestion Structure
```rust
pub struct ProactiveSuggestion {
pub agenda_id: AgendaId, // Source agenda item
pub description: String, // Human-readable text
pub kind: AgendaKind, // Type of open loop
pub mode: SurfaceMode, // How prominently to show
pub reason: SurfaceReason, // Why being surfaced
pub confidence: f64, // Relevance score [0,1]
pub urgency: f64, // Time sensitivity [0,1]
}
```
## Conflict Detection
The system detects and manages conflicts between memories and beliefs.
### Conflict Types
| Type | Default Priority | Description |
|------|-----------------|-------------|
| IdentityFact | critical | Core identity contradiction |
| Preference | high | Preference inconsistency |
| Temporal | high | Time-based conflict |
| Consolidation | medium | Merge conflict |
| Minor | low | Minor inconsistency |
资料来源：[types.rs:180-210](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)
### Conflict Resolution
Conflicts are resolved through a policy-aware process that checks namespace-specific policies before flagging inconsistencies. Resolution strategies include:
- **Timestamp-based**: Newer observation wins
- **Source-based**: Higher provenance reliability wins
- **Evidence count**: More supporting observations wins
- **Manual resolution**: User intervention required for critical conflicts
## Natural Language Understanding
The extractor component converts free-text observations into structured cognitive operations:
| Template | Resulting Operation |
|----------|-------------------|
| CreateTask | Creates new task with priority |
| CreateGoal | Creates goal with priority |
| SetPreference | Records preference in domain |
| CreateNeed | Records need with category |
| CreateRoutine | Records behavioral pattern |
| EmotionalMarker | Logs emotional state |
| CreateRelationship | Records person relationship |
| Correction | Updates belief with correction |
| TaskCompleted | Updates task status |
资料来源：[extractor.rs:150-180](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/extractor.rs)
## Narrative Arc Tracking
The system maintains narrative structures to track ongoing storylines in the user's life:
### Arc Status
| Status | Description |
|--------|-------------|
| Emerging | Recently detected, accumulating episodes |
| Active | Continuously developing |
| Paused | No recent activity, may resume |
| Resolved | Goal achieved or concluded |
| Abandoned | Intentionally stopped |
### Chapter Types
Narrative arcs are structured into chapters:
| Type | Description |
|------|-------------|
| Setup | Initial context setting |
| Rising | Building tension or progress |
| Climax | Peak moment |
| Falling | Winding down |
| Resolution | Final conclusion |
| Interlude | Pause or side-thread |
资料来源：[narrative.rs:50-80](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/narrative.rs)
## Priority Levels
Cognitive entities use a priority tier system for urgency-based processing:
| Priority | Activation Threshold | Use Case |
|----------|---------------------|----------|
| Critical | 1.00 | Safety, immediate health |
| High | 0.75 | Important deadlines |
| Medium | 0.50 | Normal tasks |
| Low | 0.25 | Nice-to-have items |
资料来源：[state.rs:240-260](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
---
## Conflict Detection and Resolution
### 相关页面
相关主题：[Cognition Layer](#page-cognition-layer), [Core API Reference](#page-core-api)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)
- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)
- [crates/yantrikdb-core/src/cognition/coherence.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/coherence.rs)
- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)
# Conflict Detection and Resolution
The Conflict Detection and Resolution system is a core cognitive subsystem within yantrikdb that identifies, categorizes, and resolves contradictions between beliefs, memories, and other cognitive nodes stored in the knowledge graph. This system ensures the internal consistency of the user's cognitive model by detecting conflicts, prioritizing them based on severity, and applying appropriate resolution strategies.
## Overview
The conflict resolution system operates as part of the broader cognitive engine, integrated with the coherence checking pipeline. When contradictions are detected between nodes in the belief network, the system evaluates the evidence supporting each conflicting belief and automatically or semi-automatically resolves the conflict.
资料来源：[crates/yantrikdb-core/src/cognition/coherence.rs]()
## Conflict Types
Conflicts in yantrikdb are categorized into five distinct types, each with different priority levels and default handling strategies.
| Conflict Type | Priority | Description |
|---------------|----------|-------------|
| `IdentityFact` | Critical | Conflicts about fundamental identity or factual information |
| `Preference` | High | Contradicting user preferences or stated likes/dislikes |
| `Temporal` | High | Time-related contradictions (scheduling, deadlines) |
| `Consolidation` | Medium | Conflicts arising from memory consolidation processes |
| `Minor` | Low | Minor inconsistencies that don't affect core beliefs |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
```rust
pub enum ConflictType {
IdentityFact,
Preference,
Temporal,
Consolidation,
Minor,
}
```
Each conflict type has an associated default priority that determines how urgently it should be addressed in the surfacing queue.
## Conflict Data Model
The `Conflict` struct captures all metadata about a detected conflict.
### Conflict Structure
| Field | Type | Description |
|-------|------|-------------|
| `conflict_id` | String | Unique identifier for the conflict |
| `conflict_type` | String | One of the five conflict types |
| `priority` | String | Priority level (critical, high, medium, low) |
| `status` | String | Current resolution status |
| `memory_a` | String | Reference ID of first conflicting memory |
| `memory_b` | String | Reference ID of second conflicting memory |
| `entity` | Option\ | Associated entity if applicable |
| `rel_type` | Option\ | Relationship type between memories |
| `detected_at` | f64 | Unix timestamp when conflict was detected |
| `detected_by` | String | Component or operator that detected the conflict |
| `detection_reason` | String | Explanation of why this is a conflict |
| `resolved_at` | Option\ | Timestamp when resolution was applied |
| `resolved_by` | Option\ | Resolution strategy or component |
| `strategy` | Option\ | Resolution strategy used |
| `winner_rid` | Option\ | Reference ID of winning memory |
| `resolution_note` | Option\ | Human-readable explanation of resolution |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
## Conflict Resolution Strategies
When a conflict is resolved, the system generates a `ConflictResolutionResult` containing details of the resolution outcome.
| Field | Type | Description |
|-------|------|-------------|
| `conflict_id` | String | The resolved conflict's identifier |
| `strategy` | String | Strategy applied (e.g., "evidence_based", "user_choice") |
| `winner_rid` | String | Reference ID of the winning memory node |
| `loser_tombstoned` | bool | Whether the losing memory was soft-deleted |
| `new_memory_rid` | Option\ | ID of newly created merged memory, if applicable |
资料来源：[crates/yantrikdb-core/src/base/types.rs]()
### Resolution Logic
The coherence checking system applies evidence-based resolution when two beliefs contradict each other. The algorithm compares the evidence count between the two conflicting nodes:
```rust
let (loser, winner_label) = match (node_a, node_b) {
(Some(a), Some(b)) => {
// Prefer keeping the one with more evidence.
if a.attrs.evidence_count >= b.attrs.evidence_count {
(b.id, a.label.clone())
} else {
(a.id, b.label.clone())
}
}
(None, Some(_)) => (contradiction.belief_a, "unknown".to_string()),
(Some(_), None) => (contradiction.belief_b, "unknown".to_string()),
(None, None) => (contradiction.belief_a, "unknown".to_string()),
};
```
The losing belief is demoted (tombstoned), and the explanation reflects which belief had higher evidence support. This approach ensures that beliefs with more corroborating evidence are preserved in the knowledge graph.
资料来源：[crates/yantrikdb-core/src/cognition/coherence.rs]()
## Conflict Surfacing
Not all conflicts require immediate user attention. The surfacing system uses the `SurfaceReason` enum to determine when and how conflicts should be presented to the user.
### Surfacing Reasons Related to Conflicts
| Reason | Base Confidence | Description |
|--------|-----------------|-------------|
| `ConflictNeedsResolution` | 0.7 | Active conflict that requires user input |
| `AnomalyDetected` | 0.65 | Statistical anomaly suggesting hidden conflict |
| `UrgencyThreshold` | 0.5 | Generic urgency-based surfacing trigger |
资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs]()
### Surfacing Modes
When a conflict is surfaced, the system selects an appropriate presentation mode based on urgency and priority:
| Mode | Disruption Cost | Use Case |
|------|----------------|----------|
| `Whisper` | 0.05 | Low-priority informational notes |
| `Nudge` | 0.25 | Moderate importance, user-initiated check |
| `Alert` | 0.60 | High-priority conflicts requiring attention |
| `Preempt` | 0.95 | Critical identity conflicts, immediate attention |
资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs]()
## Cognitive Edge Kinds and Conflict Detection
The belief network uses typed edges to represent relationships between cognitive nodes. Certain edge types are directly relevant to conflict detection.
### Epistemic Edges
Edges that participate in belief revision and conflict detection:
| Edge Kind | Activation Transfer | Role |
|-----------|---------------------|------|
| `Supports` | 0.7 | Positive evidence for a belief |
| `Contradicts` | -0.5 | Direct opposition between beliefs |
The system identifies conflicts when a `Contradicts` edge exists between two belief nodes. These edges have negative activation transfer, meaning they inhibit the target node's activation level.
资料来源：[crates/yantrikdb-core/src/cognition/state.rs]()
### Edge Classification Methods
```rust
/// Whether this edge participates in belief revision.
pub fn is_epistemic(self) -> bool {
matches!(self, Self::Supports | Self::Contradicts)
}
/// Whether this edge type is inhibitory (suppresses target activation).
pub fn is_inhibitory(self) -> bool {
self.activation_transfer() < 0.0
}
```
## Coherence Checking Pipeline
The coherence checking system is responsible for detecting conflicts as part of the cognitive processing pipeline.
### Operator Priority in Cognitive Loop
| Operator | Priority | Role |
|----------|----------|------|
| `Attend` | 10 | Foundation - always run |
| `Recall` | 9 | Critical for context |
| `Believe` | 8 | Evidence integration |
| `Compare` | 7 | Action selection |
| `Constrain` | 7 | Safety - always run if comparing |
| `Plan` | 6 | Means-ends reasoning |
| `Project` | 5 | Forward simulation |
| `Anticipate` | 4 | Proactive - nice to have |
| `Assess` | 3 | Meta - can skip under pressure |
| `CoherenceCheck` | 2 | Maintenance - skip if budget tight |
The `CoherenceCheck` operator has the lowest priority, meaning it may be skipped when computational budget is constrained. This design ensures that core cognitive functions (attention, recall, belief integration) always execute first.
资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs]()
### Fragmentation Detection
The coherence system also monitors attention fragmentation—how evenly distributed activation is across working set nodes:
```rust
fn compute_fragmentation(ws: &WorkingSet) -> f64 {
if ws.len() <= 1 {
return 0.0;
}
let activations: Vec = ws.iter().map(|n| n.attrs.activation).collect();
let total: f64 = activations.iter().sum();
if total <= 0.0 {
return 0.0;
}
// Normalized entropy (Shannon entropy / max entropy)
let n = activations.len() as f64;
// ...
}
```
High fragmentation (many nodes with similar activation) can indicate unresolved conflicts competing for attention.
资料来源：[crates/yantrikdb-core/src/cognition/coherence.rs]()
## Python API
The Python bindings expose conflict resolution through the `PyConflictEngine` interface.
### Key Methods
| Method | Parameters | Return | Description |
|--------|------------|--------|-------------|
| `list_conflicts` | `namespace`, `limit` | Vec\ | List conflicts in namespace |
| `get_conflict` | `conflict_id` | Option\ | Retrieve specific conflict |
| `resolve_conflict` | `conflict_id`, `strategy`, `winner_rid`, `new_text`, `resolution_note` | Dict | Apply resolution strategy |
资料来源：[crates/yantrikdb-python/src/py_engine/cognition.rs]()
### Resolution Example
```python
result = db.resolve_conflict(
conflict_id="conflict_123",
strategy="evidence_based",
winner_rid="memory_456",
new_text=None,
resolution_note="Preferred belief with higher evidence count"
)
```
## System Architecture
```mermaid
graph TD
subgraph "Cognitive Engine"
A[CognitiveNode Storage] --> B[CoherenceChecker]
B --> C[ConflictDetector]
C --> D[Conflict Queue]
D --> E[SurfaceReason Evaluator]
E --> F[ProactiveSuggestion Generator]
end
subgraph "Conflict Types"
G[IdentityFact]
H[Preference]
I[Temporal]
J[Consolidation]
K[Minor]
end
subgraph "Resolution Outcomes"
L[Winner Selected]
M[Loser Tombstoned]
N[New Merged Memory]
O[User Notified]
end
C --> G
C --> H
C --> I
C --> J
C --> K
F --> L
F --> M
F --> N
F --> O
```
## Provenance and Reliability
Conflicts are detected based on the provenance source of each memory node. Different provenance types have different reliability priors:
| Provenance | Reliability Prior | Description |
|------------|------------------|-------------|
| `Told` | 0.95 | User explicitly stated - highest trust |
| `Observed` | 0.90 | Directly observed behavior |
| `Experimented` | 0.85 | Confirmed via controlled experiment |
| `Consolidated` | 0.80 | Merged from multiple sources |
| `Extracted` | 0.75 | From external documents |
| `Inferred` | 0.60 | Pattern-based inference |
| `SystemDefault` | 0.50 | Default values - weakest |
When conflicts involve memories with different provenance sources, the system considers reliability priors in its resolution strategy.
资料来源：[crates/yantrikdb-core/src/cognition/state.rs]()
## Summary
The Conflict Detection and Resolution system in yantrikdb provides a robust mechanism for maintaining cognitive consistency:
1. **Detection**: Conflicts are identified through the `Contradicts` edge type in the belief network and during coherence checking operations.
2. **Classification**: Conflicts are categorized into five types with associated priority levels, enabling appropriate handling based on severity.
3. **Resolution**: Evidence-based resolution selects the belief with higher evidence count as the winner, with the losing belief being tombstoned.
4. **Surfacing**: High-priority conflicts trigger the surfacing system to proactively notify the user through appropriate channels (whisper, nudge, alert, or preempt).
5. **Integration**: The system integrates with the broader cognitive engine, respecting operator priorities and computational budgets.
---
## MCP Server Integration
### 相关页面
相关主题：[Python Bindings](#page-python-bindings)
相关源码文件
以下源码文件用于生成本页说明：
- [src/yantrikdb/mcp/server.py](https://github.com/yantrikos/yantrikdb/blob/main/src/yantrikdb/mcp/server.py)
- [src/yantrikdb/mcp/tools.py](https://github.com/yantrikos/yantrikdb/blob/main/src/yantrikdb/mcp/tools.py)
- [src/yantrikdb/mcp/resources.py](https://github.com/yantrikos/yantrikdb/blob/main/src/yantrikdb/mcp/resources.py)
- [MCP_REDESIGN.md](https://github.com/yantrikos/yantrikdb/blob/main/MCP_REDESIGN.md)
# MCP Server Integration
The MCP (Model Context Protocol) Server Integration provides a standardized interface for AI agents to interact with YantrikDB's persistent cognitive memory. This integration enables AI assistants—including Claude Code, Cursor, Windsurf, and any MCP-compatible client—to automatically remember decisions, recall relevant context, and detect contradictions without explicit user prompting.
## Overview
The MCP server is a Python-based component built on top of the FastMCP framework that exposes YantrikDB's core capabilities through the Model Context Protocol. This allows AI agents to maintain persistent memory across sessions, automatically consolidating experiences over time.
资料来源：[MCP_REDESIGN.md:1-20]()
### Core Objectives
The MCP integration was designed to achieve the following success criteria:
| Criterion | Description |
|-----------|-------------|
| Zero-configuration setup | `pip install yantrikdb[mcp]` with 3 lines in mcp.json |
| Automatic memory recall | Agent recalls relevant context at conversation start |
| Automatic memory storage | Agent remembers decisions, preferences, corrections |
| Conflict detection | Agent surfaces contradictions naturally |
| Cross-platform compatibility | Works with Claude Code, Cursor, Windsurf, and any MCP client |
| Fast first-run | Database initialization completes in under 30 seconds |
| Session persistence | Memory persists across sessions with gradual consolidation |
资料来源：[MCP_REDESIGN.md:50-58]()
## Architecture
### Component Structure
The MCP server is organized into three primary modules within `src/yantrikdb/mcp/`:
```mermaid
graph TD
A[MCP Client
Claude Code, Cursor] --> B[server.py
FastMCP Lifespan]
B --> C[tools.py
10 Tool Definitions]
B --> D[resources.py
MCP Resources]
C --> E[YantrikDB Core
Rust Engine]
D --> E
E --> F[SQLite Database
memory.db]
```
资料来源：[MCP_REDESIGN.md:25-35]()
### File Structure
| File | Purpose |
|------|---------|
| `server.py` | FastMCP server initialization, lifespan context, YantrikDB + embedder initialization |
| `tools.py` | 10 tool definitions: remember, recall, relate, entities, beliefs, conflicts, patterns, consolidate, forget, stats |
| `resources.py` | MCP resource handlers for dynamic data access |
| `__init__.py` | Main entry point for the MCP command |
资料来源：[MCP_REDESIGN.md:20-30]()
## Available Tools
The MCP server exposes 10 core tools that AI agents can invoke. Each tool is designed with rich descriptions that guide auto-pilot behavior.
资料来源：[MCP_REDESIGN.md:31-35]()
### Tool Reference
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `remember` | Store a memory with embedding | `text`, `memory_type`, `importance`, `domain`, `namespace` |
| `recall` | Retrieve semantically similar memories | `query`, `top_k`, `memory_type`, `domain`, `time_window` |
| `relate` | Create a relationship between two entities | `src`, `dst`, `rel_type` |
| `entities` | Query entity graph | `query`, `entity_type`, `top_k` |
| `beliefs` | Access the belief graph | `query`, `include_inferred` |
| `conflicts` | List detected memory conflicts | `status`, `priority`, `limit` |
| `patterns` | Discover recurring patterns | `domain`, `min_confidence`, `limit` |
| `consolidate` | Trigger memory consolidation | `aggressive` |
| `forget` | Remove specific memories | `rid` or `query` |
| `stats` | Get memory statistics | - |
资料来源：[MCP_REDESIGN.md:32-35]()
### Tool Description Quality
The tool descriptions are designed to be comprehensive, telling agents not just what each tool does but *when* to call it. This guidance supports auto-pilot behavior, similar to the instruction blocks in Claude Code's configuration.
资料来源：[MCP_REDESIGN.md:40-42]()
## Configuration
### Environment Variables
The MCP server accepts configuration through environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `YANTRIKDB_DB_PATH` | `memory.db` | Path to the SQLite database file |
| `YANTRIKDB_EMBEDDING_MODEL` | `potion-base-2M` | Embedding model to use |
| `YANTRIKDB_EMBEDDING_DIM` | 64 | Embedding dimension |
资料来源：[MCP_REDESIGN.md:36-38]()
### Installation
```bash
pip install yantrikdb[mcp]
```
After installation, the server can be started with:
```bash
yantrikdb-mcp
```
### MCP Client Configuration
Add the following to your MCP client configuration (e.g., `mcp.json`):
```json
{
"mcpServers": {
"yantrikdb": {
"command": "yantrikdb-mcp",
"env": {
"YANTRIKDB_DB_PATH": "/path/to/memory.db"
}
}
}
}
```
## Advanced Capabilities
Beyond the basic remember/recall flow, the MCP server exposes advanced YantrikDB capabilities that are available from the Rust engine but not yet fully utilized by the agent workflow.
资料来源：[MCP_REDESIGN.md:60-70]()
### RecallQuery Builder Options
The underlying Rust engine supports rich query building:
| Parameter | Type | Description |
|-----------|------|-------------|
| `top_k` | `usize` | Number of results to return |
| `memory_type` | `string` | Filter by episodic, semantic, procedural, declarative |
| `namespace` | `string` | Logical data partitioning |
| `time_window` | `(f64, f64)` | Unix timestamp range filter |
| `domain` | `string` | Subject area filter |
| `source` | `string` | Memory origin filter |
| `expand_entities` | `bool` | Include related entity details |
资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-20]()
### Conflict Resolution
The engine supports multiple conflict resolution strategies:
| Strategy | Description |
|----------|-------------|
| `keep_a` | Preserve the first memory |
| `keep_b` | Preserve the second memory |
| `merge` | Combine both memories with temporal ordering |
| `ask_user` | Defer resolution to user input |
资料来源：[MCP_REDESIGN.md:62-65]()
### Pattern Mining
Pattern mining can be configured with:
- Custom confidence thresholds
- Domain-specific pattern detection
- Temporal pattern analysis
- Entity relationship patterns
资料来源：[MCP_REDESIGN.md:63-65]()
### Personality Profile Extraction
The engine can extract personality profiles from memory interactions, enabling more personalized agent behavior over time.
资料来源：[MCP_REDESIGN.md:64-66]()
### Spaced Repetition Reinforcement
Memory access automatically triggers spaced repetition reinforcement, strengthening frequently accessed memories and allowing less-used ones to decay naturally.
资料来源：[MCP_REDESIGN.md:65-67]()
### Batch Operations
The Python bindings support batch record operations for efficiency:
```python
db = yantrikdb.YantrikDB.with_default("memory.db")
db.record_batch([
{"text": "Memory 1", "importance": 0.8},
{"text": "Memory 2", "importance": 0.6},
])
```
### Replication and Sync
YantrikDB supports CRDT-based replication for multi-device synchronization:
```python
ops = db.extract_ops_since(since_hlc=hlc, since_op_id=op_id)
db.apply_ops(ops)
```
资料来源：[crates/yantrikdb-python/src/py_engine/sync.rs:1-30]()
## Memory Types
The system supports four primary memory types, each serving distinct cognitive purposes:
| Memory Type | Purpose | Typical Use Case |
|-------------|---------|------------------|
| `episodic` | Temporal experiences and events | "Yesterday I talked about project X" |
| `semantic` | Factual knowledge and concepts | "The user prefers dark mode" |
| `procedural` | How-to knowledge and skills | "How to run the test suite" |
| `declarative` | Explicitly stated facts | "The deadline is March 30" |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:1-30]()
## Entity and Belief Management
### Entity Graph
The entity graph maintains relationships between extracted entities:
```mermaid
graph LR
A[Alice] -->|leads| B[Engineering]
B -->|part_of| C[Company]
A -->|works_with| D[Bob]
```
### Belief System
Beliefs have provenance types indicating their source reliability:
| Provenance | Reliability Prior | Description |
|------------|-------------------|-------------|
| `told` | 0.95 | User explicitly stated |
| `observed` | 0.90 | Directly observed behavior |
| `experimented` | 0.85 | Confirmed via controlled experiment |
| `extracted` | 0.75 | From external documents |
| `inferred` | 0.60 | Pattern-based inference |
| `consolidated` | 0.80 | Merged from multiple sources |
| `system_default` | 0.50 | Default values |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()
## Workflow Examples
### Basic Memory Storage and Retrieval
```python
# Using Python library directly
import yantrikdb
db = yantrikdb.YantrikDB.with_default("memory.db")
# Store a memory
db.record("Alice is the engineering lead", importance=0.8, domain="people")
# Retrieve relevant memories
results = db.recall("who leads the team?", top_k=3)
# Create a relationship
db.relate("Alice", "Engineering", "leads")
```
### Triggering Cognitive Processing
```python
# Run the think() cognition loop
db.think() # consolidate, detect conflicts, mine patterns
```
This single call triggers:
- Memory consolidation
- Conflict detection and resolution
- Pattern mining
资料来源：[README.md:1-40]()
## Cognitive Triggers
The system supports multiple trigger types for proactive memory maintenance:
| Trigger | Default Cooldown | Default Expiry | Purpose |
|---------|------------------|----------------|---------|
| `decay_review` | 3 days | 7 days | Memory decay review |
| `consolidation_ready` | 1 day | 3 days | Consolidation queue processing |
| `conflict_escalation` | 2 days | 14 days | Unresolved conflict handling |
| `temporal_drift` | 14 days | 7 days | Temporal anomaly detection |
| `redundancy` | 1 day | 7 days | Duplicate memory cleanup |
| `relationship_insight` | 7 days | 7 days | Entity relationship discovery |
| `valence_trend` | 7 days | 7 days | Emotional pattern tracking |
| `entity_anomaly` | 7 days | 7 days | Unusual entity behavior |
| `pattern_discovered` | 7 days | 7 days | New pattern identification |
资料来源：[crates/yantrikdb-core/src/base/types.rs:1-50]()
## Future Enhancements
The MCP_REDESIGN.md outlines planned improvements:
1. **Rich tool descriptions** — More detailed examples for auto-pilot behavior
2. **Server instructions** — System prompt injection for agent guidance
3. **Better error messages** — More informative feedback for debugging
4. **Streaming responses** — For long-running operations
5. **Progress indicators** — Real-time feedback during consolidation
资料来源：[MCP_REDESIGN.md:45-55]()
## See Also
- [YantrikDB Core Engine](../core/engine.md)
- [Python API Reference](../python/api.md)
- [Conflict Resolution](../core/conflict-resolution.md)
- [Consolidation System](../core/consolidation.md)
---
## Python Bindings
### 相关页面
相关主题：[MCP Server Integration](#page-mcp-server), [Installation](#page-installation), [Core API Reference](#page-core-api)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)
- [crates/yantrikdb-python/src/py_engine/session_temporal.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/session_temporal.rs)
- [crates/yantrikdb-python/src/py_types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_types.rs)
- [crates/yantrikdb-core/src/engine/recall.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/recall.rs)
- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)
# Python Bindings
## Overview
The Python bindings provide a native Python interface to yantrikdb, enabling Python developers to interact with the memory database using familiar Python idioms. Built on top of the Rust core using [pyo3](https://pyo3.rs/), the bindings expose the full functionality of yantrikdb while maintaining Pythonic conventions for parameter ordering and default values.
The `PyYantrikDB` class serves as the primary entry point, offering methods for recording memories, querying with semantic search, managing relationships between entities, and triggering cognitive consolidation processes.
## Architecture
```mermaid
graph TD
A[Python Application] --> B[PyYantrikDB]
B --> C[pyo3 Bridge Layer]
C --> D[yantrikdb-core]
D --> E[SQLite Storage]
D --> F[Vector Index]
G[py_types.rs] --> C
G --> H[Type Conversions]
H --> I[PyObject ↔ Rust Structs]
J[Default Embedder] --> B
J --> K[potion-base-2M
dim=64]
```
The binding layer consists of three main components:
| Component | File | Purpose |
|-----------|------|---------|
| PyYantrikDB | `py_engine/mod.rs` | Main Python class exposing all methods |
| Type Conversions | `py_types.rs` | Bidirectional conversion between Rust and Python types |
| Engine Bridge | `py_engine/*.rs` | Method implementations delegating to core |
## Core API Methods
### Recording Memories
The `record()` method stores new memories in the database with semantic embeddings. It accepts text input and generates embeddings automatically using the bundled embedder, or accepts pre-computed embeddings for efficiency.
```python
db.record(
text="Alice is the engineering lead",
memory_type="episodic",
importance=0.8,
valence=0.0,
half_life=604800.0,
certainty=0.8,
domain="people",
source="user",
namespace="default",
emotional_state=None
)
```
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | `str` | Required | The memory content to store |
| `memory_type` | `str` | `"episodic"` | Memory classification (episodic, semantic, etc.) |
| `importance` | `float` | `0.5` | Significance score [0.0, 1.0] |
| `valence` | `float` | `0.0` | Emotional valence [-1.0, 1.0] |
| `half_life` | `float` | `604800.0` | Decay period in seconds (7 days default) |
| `certainty` | `float` | `0.8` | Confidence in the memory's accuracy |
| `domain` | `str` | `"general"` | Knowledge domain category |
| `source` | `str` | `"user"` | Origin of the memory |
| `namespace` | `str` | `"default"` | Logical partition for data isolation |
| `emotional_state` | `str` | `None` | Emotional context at recording time |
| `embedding` | `List[float]` | `None` | Pre-computed vector (auto-generated if omitted) |
| `metadata` | `dict` | `None` | Arbitrary key-value metadata |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:13-30]()
### Querying and Recall
The `recall()` method performs semantic search over stored memories, returning results ranked by relevance. It supports both text queries and pre-computed embedding vectors.
```python
results = db.recall(
query="who leads the team?",
top_k=10,
memory_type=None,
namespace=None,
time_window=None,
include_consolidated=False,
expand_entities=True,
skip_reinforce=False,
domain=None,
source=None
)
```
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | `str` | `None` | Natural language search query |
| `query_embedding` | `List[float]` | `None` | Pre-computed embedding vector |
| `top_k` | `int` | `10` | Maximum results to return |
| `time_window` | `Tuple[float, float]` | `None` | Filter by Unix timestamp range |
| `memory_type` | `str` | `None` | Filter by memory type |
| `namespace` | `str` | `None` | Filter by namespace |
| `domain` | `str` | `None` | Filter by domain |
| `source` | `str` | `None` | Filter by source |
| `include_consolidated` | `bool` | `False` | Include consolidated memories |
| `expand_entities` | `bool` | `True` | Expand entity references |
| `skip_reinforce` | `bool` | `False` | Skip reinforcement learning update |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:60-85]()
The `recall_text()` method provides a simplified interface for text-based queries with optional filtering:
```python
results = db.recall_text(
query="who leads the team?",
top_k=10,
namespace=None,
domain=None,
source=None
)
```
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:125-145]()
### Procedural Memory
Procedural memory stores task-related information and supports reinforcement learning for effectiveness tracking.
```python
# Record a procedural memory
rid = db.record_procedural(
text="How to deploy to production",
domain="devops",
task_context="deployment workflow",
effectiveness=0.5,
namespace="default"
)
# Reinforce based on outcome
db.reinforce_procedural(rid, outcome=0.9)
```
**Parameters for `record_procedural`:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | `str` | Required | Procedure description |
| `embedding` | `List[float]` | `None` | Pre-computed vector |
| `domain` | `str` | `"general"` | Task domain |
| `task_context` | `str` | `""` | Contextual information |
| `effectiveness` | `float` | `0.5` | Initial effectiveness score |
| `namespace` | `str` | `"default"` | Namespace partition |
资料来源：[crates/yantrikdb-python/src/py_engine/session_temporal.rs:45-60]()
### Memory Correction
The `correct()` method allows updating existing memories with corrections, maintaining an audit trail of original content.
```python
result = db.correct(
rid="existing-memory-rid",
new_text="Updated information",
new_importance=0.9,
new_valence=0.2,
embedding=None,
correction_note="Corrected factual error"
)
```
**Return Value:**
| Field | Type | Description |
|-------|------|-------------|
| `original_rid` | `str` | ID of the original memory |
| `corrected_rid` | `str` | ID of the new corrected memory |
| `original_tombstoned` | `bool` | Whether original was soft-deleted |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:100-115]()
### Memory Decay
The `decay()` method triggers decay calculations across all memories based on access patterns and half-life values.
```python
decayed = db.decay(threshold=0.01)
```
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `threshold` | `float` | `0.01` | Minimum importance to retain |
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:88-95]()
## Default Embedding Model
The Python bindings include a bundled embedder (`potion-base-2M`) that provides 64-dimensional embeddings out of the box. This eliminates dependencies on external services like sentence-transformers or ONNX runtime.
```mermaid
graph LR
A[Input Text] --> B[pyo3 embed_text]
B --> C[potion-base-2M]
C --> D[64-dim Vector]
D --> E[Storage/Recall]
```
The embedder is invoked automatically when `embedding` parameters are omitted:
```python
# Auto-embedding
db.record("Alice is the engineering lead")
# Manual embedding
vector = [0.1, 0.2, ...] # 64 floats
db.record("Alice is the engineering lead", embedding=vector)
```
资料来源：[README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)
## Initialization and Configuration
### Creating a Database Instance
```python
import yantrikdb
# Default instance with bundled embedder
db = yantrikdb.YantrikDB.with_default("memory.db")
# Work with the database
db.record("Memory content", importance=0.8)
results = db.recall("Query text")
# Always close when done
db.close()
```
资料来源：[README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)
## Type Conversions
The `py_types.rs` module handles bidirectional conversion between Rust structs and Python objects:
| Rust Type | Python Type | Conversion Function |
|-----------|-------------|---------------------|
| `yantrikdb_core::Memory` | `dict` | `memory_to_dict()` |
| `yantrikdb_core::RecallResult` | `dict` | `recall_result_to_dict()` |
| `serde_json::Value` | `PyObject` | `json_to_py()` |
| `Bound` | `serde_json::Value` | `py_to_json()` |
资料来源：[crates/yantrikdb-python/src/py_types.rs:6-40]()
### Memory to Dictionary
The `memory_to_dict()` function converts a core Memory struct to a Python dictionary matching the Python engine's expected output format:
```rust
pub fn memory_to_dict(py: Python<'_>, mem: &yantrikdb_core::Memory) -> PyResult {
let dict = PyDict::new(py);
dict.set_item("rid", &mem.rid)?;
dict.set_item("type", &mem.memory_type)?;
dict.set_item("text", &mem.text)?;
dict.set_item("created_at", mem.created_at)?;
dict.set_item("importance", mem.importance)?;
// ... additional fields
Ok(dict.into())
}
```
资料来源：[crates/yantrikdb-python/src/py_types.rs:8-25]()
## Return Value Structure
### Recall Results
Query results are returned as Python dictionaries with the following structure:
```python
{
"rid": "memory-unique-id",
"type": "episodic",
"text": "Memory content",
"score": 0.95, # Relevance score
"created_at": 1234567890.0,
"importance": 0.8,
"valence": 0.0,
"half_life": 604800.0,
"last_access": 1234567890.0,
"access_count": 5,
"consolidation_status": "stable",
"storage_tier": "hot",
"namespace": "default",
"certainty": 0.8,
"domain": "people",
"source": "user",
"emotional_state": None,
"metadata": {}
}
```
## Advanced Query Options
### Recall with Sequence Verification
For applications requiring strong consistency guarantees, `recall_with_seq()` ensures query results reflect all prior writes:
```python
# After a write operation
db.record("New memory", namespace="work")
# Ensure subsequent recall sees the write
results = db.recall_with_seq(
query_embedding=embedding,
top_k=10,
min_seq=prior_sequence,
namespace="work",
timeout=timedelta(seconds=5)
)
```
资料来源：[crates/yantrikdb-core/src/engine/recall.rs:50-80]()
### Time-Window Filtering
Results can be filtered to a specific time range using Unix timestamps:
```python
import time
now = time.time()
week_ago = now - 604800 # 7 days
results = db.recall(
query="meetings",
time_window=(week_ago, now)
)
```
## Memory Types
yantrikdb supports multiple memory types for different kinds of information:
| Type | Description |
|------|-------------|
| `entity` | Factual knowledge about entities |
| `episode` |事件性记忆 |
| `belief` | User beliefs and opinions |
| `goal` | Goals and objectives |
| `task` | Tasks and action items |
| `intent_hypothesis` | Hypothesized user intents |
| `routine` | Recurring behavioral patterns |
| `need` | User needs and requirements |
| `opportunity` | Time-bounded opportunities |
| `risk` | Potential problems |
| `preference` | User preferences |
| `conversation_thread` | Conversational context |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:120-145]()
## Relationship Management
Beyond storing individual memories, yantrikdb supports graph-like relationships between entities:
```python
# Define relationships
db.relate("Alice", "Engineering", "leads")
db.relate("Alice", "Bob", "manages")
# Query relationships
edges = db.get_edges("Alice")
```
The system supports relationship types including:
| Type | Description |
|------|-------------|
| `supports` | Supporting evidence |
| `contradicts` | Contradicting information |
| `causes` | Causal relationship |
| `predicts` | Predictive relationship |
| `requires` | Prerequisite relationship |
| `associated_with` | General association |
| `similar_to` | Similarity connection |
资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-230]()
## Cognitive Processing
### Think Operation
The `think()` method triggers the cognitive processing pipeline:
```python
db.think() # Consolidate, detect conflicts, mine patterns
```
This operation:
1. Consolidates related memories
2. Detects conflicts between beliefs
3. Mines patterns from episodic data
4. Updates procedural memory effectiveness
## Error Handling
The Python bindings map Rust errors to appropriate Python exceptions:
| Rust Error | Python Exception |
|------------|------------------|
| `RuntimeError` | `RuntimeError` |
| `ValueError` | `ValueError` |
| Storage errors | `RuntimeError` |
```python
try:
db.record("Memory")
except RuntimeError as e:
print(f"Database error: {e}")
except ValueError as e:
print(f"Invalid input: {e}")
```
资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:20-25]()
## Best Practices
1. **Always close the database** when done to ensure proper cleanup:
```python
db = yantrikdb.YantrikDB("memory.db")
try:
# operations
finally:
db.close()
```
2. **Use context managers** when possible for automatic cleanup
3. **Batch operations** when recording multiple related memories
4. **Choose appropriate namespaces** to partition data logically
5. **Set importance values** appropriately to control memory retention and retrieval priority
---
---
## Doramagic 踩坑日志
项目：yantrikos/yantrikdb
摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。
## 1. 安装坑 · 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安装坑 · 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 10. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code
## 11. 配置坑 · 来源证据：v0.7.7 — recall_text Keyword-Only Filter Args
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass.
## 13. 运行坑 · 来源证据：think() runs consolidation before conflict detection — contradictions get merged
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing
## 15. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium
## 16. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use.
## 17. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium
## 18. 安全/权限坑 · 来源证据：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_80497be2ab644e66be4fec1a966b4c10 | https://github.com/yantrikos/yantrikdb/issues/7 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 19. 安全/权限坑 · 来源证据：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ca7c8f7ee1384f9d97652734d01b8d67 | https://github.com/yantrikos/yantrikdb/issues/3 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 20. 安全/权限坑 · 来源证据：v0.7.6 — Drop sentence-transformers + numpy from Default Deps
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.6 — Drop sentence-transformers + numpy from Default Deps
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_40bcf8933f1b4ec7a559a746497c3bae | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.6 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 21. 安全/权限坑 · 来源证据：v0.7.8 — Extended Idempotent Migration Runner (closes #10)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.8 — Extended Idempotent Migration Runner (closes #10)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e5a77701b7ac401a863105d996cb585c | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8 | 来源类型 github_release 暴露的待验证使用条件。
## 22. 安全/权限坑 · 来源证据：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7a590e518c884b5b9a2bbdc995c372fd | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 23. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | issue_or_pr_quality=unknown
## 24. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | release_recency=unknown