forge-memory

Native Akasha-backed memory integration for the Forge SDK

Package contract

Field	Value
Language	rust
Source version	0.2.0
Manifest	`forge-rs/crates/forge-memory/Cargo.toml`
Source files	6
Evidence	Source reference; registry publication and runtime conformance are separate checks

Import boundary

use forge_memory;

Use a source checkout or your verified private registry. Manifest coordinates identify the package; they do not establish that a public registry release exists.

Crate boundary

The following entries are taken from src/lib.rs. Feature conditions in the exact source still apply.

pub mod error;

pub mod policy;

pub mod scope;

pub mod store;

pub mod types;

pub use error::{MemoryError, MemoryResult};

pub use policy::{RetrievalPolicy, WriteBackPolicy, WriteBackTrigger};

pub use scope::MemoryScope;

pub use store::{AgentMemory, InMemoryStore, MemoryStore};

pub use types::{MemoryEntry, MemoryEntryBuilder, MemoryId, MemoryQuery, MemoryType};

Download package reference JSON. Each original source file and generated declaration artifact has its own SHA-256 digest. Function bodies and constant values are omitted from downloads. These are source declaration inventories, not compiler-resolved rustdoc, TypeDoc, DocC, or Dokka output. Private modules can contain public declarations that are not reachable through the package boundary; consult the entry point before importing.

error.rs

Read declaration text · 2 declaration entries

#[derive(Debug, Error)]
pub enum MemoryError {
    /// A memory entry was not found.
    #[error("memory entry '{memory_id}' not found in scope '{scope}'")]
    NotFound {
        /// The memory ID that was looked up.
        memory_id: String,
        /// The scope that was searched.
        scope: String,
    },

    /// Access to a memory scope was denied.
    #[error("agent '{agent_id}' denied access to memory scope '{scope}': {reason}")]
    AccessDenied {
        /// The agent that was denied.
        agent_id: String,
        /// The scope that was requested.
        scope: String,
        /// Why access was denied.
        reason: String,
    },

    /// A write-back operation failed.
    #[error("write-back failed for entry '{memory_id}' in scope '{scope}': {reason}")]
    WriteBackFailed {
        /// The memory ID that failed to persist.
        memory_id: String,
        /// The scope the entry was in.
        scope: String,
        /// What went wrong.
        reason: String,
    },

    /// The memory store backend returned an error.
    #[error("memory store error: {reason}")]
    StoreError {
        /// The backend error description.
        reason: String,
    },

    /// A memory query was invalid.
    #[error("invalid memory query: {reason}")]
    InvalidQuery {
        /// What is wrong with the query.
        reason: String,
    },

    /// Serialization or deserialization failed.
    #[error("memory serialization error: {0}")]
    Serialization(#[from] serde_json::Error),
}

pub type MemoryResult<T> = Result<T, MemoryError>;

lib.rs

Read declaration text · 10 declaration entries

pub mod error;

pub mod policy;

pub mod scope;

pub mod store;

pub mod types;

pub use error::{MemoryError, MemoryResult};

pub use policy::{RetrievalPolicy, WriteBackPolicy, WriteBackTrigger};

pub use scope::MemoryScope;

pub use store::{AgentMemory, InMemoryStore, MemoryStore};

pub use types::{MemoryEntry, MemoryEntryBuilder, MemoryId, MemoryQuery, MemoryType};

policy.rs

Read declaration text · 29 declaration entries

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RetrievalPolicy {

}

pub fn builder() -> RetrievalPolicyBuilder;

pub fn can_read_scope(&self, scope: &MemoryScope) -> bool;

pub fn can_read_type(&self, memory_type: &MemoryType) -> bool;

pub fn min_confidence(&self) -> f32;

pub fn max_results(&self) -> usize;

#[derive(Debug, Default)]
pub struct RetrievalPolicyBuilder {

}

pub fn new() -> Self;

pub fn allow_scope(mut self, scope: MemoryScope) -> Self;

pub fn allow_type(mut self, memory_type: MemoryType) -> Self;

pub fn min_confidence(mut self, min: f32) -> Self;

pub fn max_results(mut self, max: usize) -> Self;

pub fn build(self) -> RetrievalPolicy;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WriteBackTrigger {
    /// Write immediately when store() is called.
    Immediate,
    /// Batch writes and flush periodically.
    Batched,
    /// Only write back on explicit flush or session close.
    OnFlush,
    /// Never persist (task-scoped, discarded on completion).
    Never,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WriteBackPolicy {

}

pub fn builder() -> WriteBackPolicyBuilder;

pub fn trigger(&self) -> WriteBackTrigger;

pub fn can_write_scope(&self, scope: &MemoryScope) -> bool;

pub fn min_confidence_for_persistence(&self) -> f32;

pub fn batch_size(&self) -> usize;

pub fn batch_interval_seconds(&self) -> u64;

#[derive(Debug, Default)]
pub struct WriteBackPolicyBuilder {

}

pub fn new() -> Self;

pub fn trigger(mut self, trigger: WriteBackTrigger) -> Self;

pub fn allow_scope(mut self, scope: MemoryScope) -> Self;

pub fn min_confidence_for_persistence(mut self, min: f32) -> Self;

pub fn batch_size(mut self, size: usize) -> Self;

pub fn batch_interval_seconds(mut self, seconds: u64) -> Self;

pub fn build(self) -> WriteBackPolicy;

scope.rs

Read declaration text · 5 declaration entries

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
#[serde(rename_all = "snake_case")]
pub enum MemoryScope {
    /// Agent-local memory. Private to the agent instance.
    Agent,
    /// Task-scoped memory. Discarded when the task completes.
    Task,
    /// Team/project-scoped memory. Shared within a team.
    Team,
    /// Organization-wide memory. Accessible by all authorized agents.
    Org,
}

pub fn as_str(&self) -> &'static str;

pub fn is_narrower_than(&self, other: &MemoryScope) -> bool;

pub fn is_wider_than(&self, other: &MemoryScope) -> bool;

pub fn namespace(&self, owner_id: &str) -> String;

store.rs

Read declaration text · 14 declaration entries

#[async_trait]
pub trait MemoryStore: Send + Sync {
    /// Stores a memory entry and returns its ID.
    ///
    /// # Errors
    ///
    /// Returns `MemoryError::StoreError` if the backend fails.
    async fn store(&self, entry: MemoryEntry) -> MemoryResult<MemoryId>;

    /// Searches for memories matching the query.
    ///
    /// Returns entries sorted by relevance (best match first).
    ///
    /// # Errors
    ///
    /// Returns `MemoryError::StoreError` if the backend fails.
    async fn recall(&self, query: &MemoryQuery) -> MemoryResult<Vec<MemoryEntry>>;

    /// Retrieves a specific memory entry by ID.
    ///
    /// # Errors
    ///
    /// Returns `MemoryError::NotFound` if the entry does not exist.
    async fn get(&self, id: &MemoryId) -> MemoryResult<MemoryEntry>;

    /// Deletes a memory entry by ID.
    ///
    /// # Errors
    ///
    /// Returns `MemoryError::NotFound` if the entry does not exist.
    async fn delete(&self, id: &MemoryId) -> MemoryResult<()>;

    /// Lists all memories in a given scope.
    ///
    /// # Errors
    ///
    /// Returns `MemoryError::StoreError` if the backend fails.
    async fn list_by_scope(&self, scope: MemoryScope) -> MemoryResult<Vec<MemoryEntry>>;

    /// Returns the total number of stored entries.
    async fn count(&self) -> MemoryResult<usize>;
}

pub struct InMemoryStore {

}

pub fn new() -> Self;

pub struct AgentMemory {

}

pub fn new(
        agent_id: impl Into<String>,
        store: Box<dyn MemoryStore>,
        retrieval_policy: RetrievalPolicy,
        write_back_policy: WriteBackPolicy,
    ) -> Self;

pub fn agent_id(&self) -> &str;

pub fn retrieval_policy(&self) -> &RetrievalPolicy;

pub fn write_back_policy(&self) -> &WriteBackPolicy;

pub async fn store(&mut self, entry: MemoryEntry) -> MemoryResult<MemoryId>;

pub async fn recall(&self, query_text: &str, limit: usize) -> MemoryResult<Vec<MemoryEntry>>;

pub async fn recall_with_query(&self, query: &MemoryQuery) -> MemoryResult<Vec<MemoryEntry>>;

pub async fn get(&self, id: &MemoryId) -> MemoryResult<MemoryEntry>;

pub async fn delete(&self, id: &MemoryId) -> MemoryResult<()>;

pub async fn count(&self) -> MemoryResult<usize>;

types.rs

Read declaration text · 43 declaration entries

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct MemoryId(String);

pub fn new() -> Self;

pub fn from_string(id: impl Into<String>) -> Self;

pub fn as_str(&self) -> &str;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryType {
    /// Episodic memory — temporal events, interactions, experiences.
    Episodic,
    /// Semantic memory — facts, knowledge, relationships.
    Semantic,
    /// Procedural memory — skills, workflows, executable procedures.
    Procedural,
    /// Associative memory — pattern completion, content-addressable recall.
    Associative,
}

pub fn as_str(&self) -> &'static str;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MemoryEntry {

}

pub fn builder() -> MemoryEntryBuilder;

pub fn id(&self) -> &MemoryId;

pub fn content(&self) -> &str;

pub fn memory_type(&self) -> MemoryType;

pub fn scope(&self) -> MemoryScope;

pub fn confidence(&self) -> f32;

pub fn importance(&self) -> f32;

pub fn created_at(&self) -> DateTime<Utc>;

pub fn updated_at(&self) -> DateTime<Utc>;

pub fn source(&self) -> Option<&str>;

pub fn tags(&self) -> &[String];

pub fn metadata(&self) -> &HashMap<String, serde_json::Value>;

#[derive(Debug)]
pub struct MemoryEntryBuilder {

}

pub fn new() -> Self;

pub fn content(mut self, content: impl Into<String>) -> Self;

pub fn memory_type(mut self, memory_type: MemoryType) -> Self;

pub fn scope(mut self, scope: MemoryScope) -> Self;

pub fn confidence(mut self, confidence: f32) -> Self;

pub fn importance(mut self, importance: f32) -> Self;

pub fn source(mut self, source: impl Into<String>) -> Self;

pub fn tag(mut self, tag: impl Into<String>) -> Self;

pub fn meta(mut self, key: impl Into<String>, value: serde_json::Value) -> Self;

pub fn build(self) -> MemoryEntry;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MemoryQuery {

}

pub fn new(text: impl Into<String>) -> Self;

pub fn with_scope(mut self, scope: MemoryScope) -> Self;

pub fn with_type(mut self, memory_type: MemoryType) -> Self;

pub fn with_tag(mut self, tag: impl Into<String>) -> Self;

pub fn with_limit(mut self, limit: usize) -> Self;

pub fn with_min_confidence(mut self, min: f32) -> Self;

pub fn text(&self) -> &str;

pub fn scope(&self) -> Option<MemoryScope>;

pub fn memory_type(&self) -> Option<MemoryType>;

pub fn tags(&self) -> &[String];

pub fn limit(&self) -> usize;

pub fn min_confidence(&self) -> Option<f32>;