Struct ProjectKnowledge 

pub struct ProjectKnowledge {
    pub project_root: String,
    pub project_hash: String,
    pub facts: Vec<KnowledgeFact>,
    pub patterns: Vec<ProjectPattern>,
    pub history: Vec<ConsolidatedInsight>,
    pub updated_at: DateTime<Utc>,
    pub judged_pairs: Vec<JudgedPair>,
    pub index: KnowledgeIndex,
    pub withheld: Vec<WithheldKnowledge>,
}

Fields

project_root: String

project_hash: String

facts: Vec<KnowledgeFact>

patterns: Vec<ProjectPattern>

history: Vec<ConsolidatedInsight>

updated_at: DateTime<Utc>

judged_pairs: Vec<JudgedPair>

index: KnowledgeIndex

Ephemeral recall index. It is rebuilt after JSON load and never persisted, preserving the on-disk knowledge format for existing projects.

withheld: Vec<WithheldKnowledge>

Records excluded from this read view. Never serialized or exposed by a formatter; the checked persistence path retains them without modification.

Implementations

impl ProjectKnowledge

pub fn run_memory_lifecycle( &mut self, policy: &MemoryPolicy, ) -> Result<LifecycleReport, String>

The quality lifecycle (decay, merge of near-duplicates, archival of low-confidence and stale facts). There is no count cap: knowledge grows without limit (owner decision 24.10.). Writes never run it — a pass over the whole store per write does not scale — the background cognition loop does, and reports its failures.

pub fn new(project_root: &str) -> Self

pub fn rebuild_index(&mut self)

Rebuilds the transient lookup tables after loading or changing facts. The maps are intentionally excluded from JSON serialization.

pub fn check_contradiction( &self, category: &str, key: &str, new_value: &str, policy: &MemoryPolicy, ) -> Option<Contradiction>

pub fn remember( &mut self, category: &str, key: &str, value: &str, session_id: &str, confidence: f32, policy: &MemoryPolicy, ) -> Option<Contradiction>

pub fn remember_admitted( &mut self, category: &str, key: &str, value: &str, session_id: &str, confidence: f32, policy: &MemoryPolicy, ) -> AdmissionResult

Write-time admission gate for the agent-facing ctx_knowledge remember path (#970). Unlike Self::remember (which every internal restorer also calls), this enforces the crate::core::memory_policy::AdmissionPolicy: near-duplicates are merged instead of inserted, and low-salience noise is kept out of the capped store — so eviction never has to drop a good fact to make room for a paraphrase. Internal callers (archive rehydrate, cognition auto-promotion) keep using Self::remember and are never gated.

pub fn add_pattern( &mut self, pattern_type: &str, description: &str, examples: Vec<String>, session_id: &str, policy: &MemoryPolicy, )

pub fn remove_fact(&mut self, category: &str, key: &str) -> bool

impl ProjectKnowledge

pub fn consolidate( &mut self, summary: &str, session_ids: Vec<String>, policy: &MemoryPolicy, ) -> Result<usize, String>

Record one consolidated insight, then losslessly reclaim history to its capacity headroom. Returns the number of older insights archived (0 when under cap).

pub fn delivery_filter(&self) -> impl Fn(&KnowledgeFact) -> bool + '_

The delivery rule of every renderer in this file: whether a fact of this store may enter model-visible output now. It is the one function fact_served — a fact bound to sources at its write is re-authorized and left out when a source no longer admits; a fact without a binding is delivered as before and marks the call’s capture incomplete. Without protection nothing is asked (one policy read per rendering, not one per fact).

A fact is bound under the project root its writer’s request named. That is this store’s root; a request that names the project by another spelling is asked as well, so a binding is never missed by its key.

pub fn format_summary(&self) -> String

pub fn format_aaak(&self) -> String

pub fn format_aaak_delta(&self, last_hash: Option<&str>) -> AaakDelta

impl ProjectKnowledge

pub fn format_aaak_budgeted(&self, token_budget: usize) -> String

pub fn format_wakeup(&self) -> String

pub fn format_wakeup_top(&self, max_facts: usize) -> String

The wake-up facts block with at most max_facts facts, most salient first; empty for 0.

impl ProjectKnowledge

pub fn import_facts( &mut self, incoming: Vec<KnowledgeFact>, merge: ImportMerge, session_id: &str, ) -> ImportResult

Import facts from an external source with a configurable merge strategy. Returns (added, skipped, replaced) counts.

pub fn export_simple(&self) -> Vec<SimpleFactEntry>

Export current facts as a simple JSON array (community-compatible schema).

impl ProjectKnowledge

pub fn add_fact(&mut self, fact: KnowledgeFact) -> bool

Return the most recent active decision-like facts for session handoff. Adds a pre-built fact, coalescing repeated observations into confirmations.

pub fn recent_decisions(&self, limit: usize) -> Vec<KnowledgeFact>

pub fn search_semantic(&self, query: &str, limit: usize) -> Vec<KnowledgeFact>

Keyword-based knowledge search across all facts. Serves as the API surface for semantic retrieval; currently falls back to substring matching. When the embedding model is loaded, this will use HNSW vector search instead.

pub fn list_project_roots() -> Result<Vec<String>, String>

pub fn load_for_admission( project_root: &str, admission: &KnowledgeAdmission, ) -> Result<Option<Self>, String>

Load one admitted, non-migrating read view for an export operation. Hidden rows are omitted from the view and never rewrite the durable store.

pub fn load_for_checked_capture(project_root: &str) -> Result<Self, String>

Optional capture must not trigger legacy migration writes during a read, or replace an unreadable existing store with a newly created empty one.

pub fn save(&self) -> Result<(), String>

pub fn with_project_lock<T>(project_root: &str, f: impl FnOnce() -> T) -> T

Runs f while holding this project’s locks — the in-process per-hash mutex and the cross-process advisory file lock — without loading or saving the knowledge JSON itself. mutate_locked is built on this, and side-car stores that must stay consistent with the facts (today: the embedding index) call it directly so their read-modify-write is serialized against parallel remember/remove/reindex. That side-car write used to run lock-free, so concurrent callers clobbered each other’s embeddings and pruned just-stored vectors, degrading semantic recall (issue #412, a #326 follow-up).

pub fn mutate_locked<T>( project_root: &str, f: impl FnOnce(&mut Self) -> T, ) -> Result<(Self, T), String>

pub fn mutate_locked_with_admission<T>( project_root: &str, admission: &KnowledgeAdmission, f: impl FnOnce(&mut Self) -> T, ) -> Result<(Self, T), String>

pub fn load(project_root: &str) -> Option<Self>

pub fn load_or_create(project_root: &str) -> Self

pub fn migrate_legacy_empty_root( target_root: &str, policy: &MemoryPolicy, ) -> Result<bool, String>

Migrates legacy knowledge that was accidentally stored under an empty project_root (“”) into the given target_root. Keeps a timestamped backup of the legacy file.

impl ProjectKnowledge

pub fn recall(&self, query: &str) -> Vec<&KnowledgeFact>

pub fn recall_for_task(&self, task: &str) -> Vec<&KnowledgeFact>

Recall for a free-text task description (overview, sub-agent briefing).

Unlike Self::recall, which serves an explicit knowledge query, a task sentence is mostly framing: “Inspect alpha parser header validation.” shares only “inspect” with an unrelated fact about deployments, and that single word used to be enough to present the fact as relevant (#1832). Only the task’s content words are matched, tokenized the way the index is, so a task made of nothing but generic words recalls nothing.

pub fn recall_by_category(&self, category: &str) -> Vec<&KnowledgeFact>

pub fn recall_at_time( &self, query: &str, at: DateTime<Utc>, ) -> Vec<&KnowledgeFact>

pub fn timeline(&self, category: &str) -> Vec<&KnowledgeFact>

pub fn list_rooms(&self) -> Vec<(String, usize)>

pub fn recall_for_output( &mut self, query: &str, limit: usize, ) -> (Vec<KnowledgeFact>, usize)

pub fn recall_by_category_for_output( &mut self, category: &str, limit: usize, ) -> (Vec<KnowledgeFact>, usize)

impl ProjectKnowledge

pub fn admit_sources(self) -> Self

Trait Implementations

impl Clone for ProjectKnowledge

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProjectKnowledge

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ProjectKnowledge

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ProjectKnowledge

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.