plugmem_host/lib.rs
1//! The crate README is included below as module documentation, which makes
2//! every Rust example in it a doctest: a README that drifts from the API stops
3//! compiling instead of quietly lying.
4#![doc = include_str!("../README.md")]
5//! Native host layer for the plugmem engine: file-backed storage with
6//! exclusive locking, a thread-safe database handle with a maintenance
7//! policy, and embedding providers.
8//!
9//! This crate is the "point it at a file and go" Rust experience:
10//!
11//! ```no_run
12//! use plugmem_host::{Config, Database, RecallQuery, RememberInput};
13//!
14//! let (db, _report) = Database::open("agent.plugmem", Config::default())?;
15//! db.remember(RememberInput::text(1_784_000_000_000, "prefers tokio"))?;
16//! let out = db.recall(RecallQuery::text(1_784_000_100_000, "runtime?"))?;
17//! println!("{}", out.rendered);
18//! # Ok::<(), plugmem_host::HostError>(())
19//! ```
20//!
21//! Concurrency model: one local database has one owning process —
22//! a second open is refused with [`HostError::Locked`]; within the
23//! process, clone the [`Database`] handle across threads and agents;
24//! different files are fully independent. Embedding calls run outside
25//! the database lock.
26//!
27//! With the default `config` feature, the host also accepts the shared
28//! `config.toml` format through [`Settings::load`] and [`read_config`]. The
29//! `SETTINGS.md` file is the reference documentation for that format, not an
30//! input file. Disable the feature with `default-features = false` when a
31//! caller wants only programmatic [`Config`] construction.
32
33mod db;
34mod embedder;
35mod error;
36mod paths;
37mod readonly;
38#[cfg(feature = "config")]
39mod settings;
40#[cfg(feature = "config")]
41mod settings_help;
42mod storage;
43mod workspace;
44
45pub use db::{Database, DatabaseBuilder, ExportPage, ExportedFact, FactSnapshot, RecoverReport};
46pub use embedder::{Embedder, NullEmbedder, OpenAiCompatEmbedder, SharedEmbedder};
47pub use error::HostError;
48pub use paths::{default_config_dir, default_config_path, default_data_dir, default_database_path};
49pub use readonly::{ReadOnlyDatabase, Scrub};
50#[cfg(feature = "config")]
51pub use settings::{Settings, SettingsError, WorkspaceSettings, read_config};
52#[cfg(feature = "config")]
53pub use settings_help::{SettingDoc, SettingScope, SettingWarning, SettingsHelp, settings_help};
54pub use storage::{FileScratch, FileStorage, FsyncPolicy};
55pub use workspace::{
56 ARCHIVED_TAG, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_OPEN, DbEntry, DbName, Description,
57 ENTRY_TAG, IfMissing, MAX_DB_NAME, MAX_OPEN_CEILING, NameProblem, Opener, ReindexReport,
58 SELF_ENTITY, Workspace, WorkspaceError, WorkspaceIssue, WorkspaceLayout, WorkspaceLimits,
59};
60
61// The engine types a host caller works with, re-exported so simple
62// embedders need only this crate.
63pub use plugmem_core::snapshot::{DEFAULT_SCRUB_BUDGET, ScrubProgress};
64pub use plugmem_core::{
65 Config, EdgeId, EntityId, Error, FactId, FactRecord, LinkInput, MaintainReport,
66 MaintenanceMode, MaintenanceOptions, OpenReport, RecallQuery, RecallResult, RecallScratch,
67 RecalledEdge, RecalledFact, RememberInput, RememberOutcome, ShardLayout, Similar,
68 SimilarReason, Stats, UnlinkInput, VALID_TO_OPEN, fact_flags,
69};
70pub use plugmem_core::{MemScratch, Scratch};