mnemos

Knowledge, recall, retrieval, and memory for Converge formations.

mnemos is a Converge extension. It implements knowledge-base storage, retrieval, ingestion, embeddings, feedback learning, and Converge suggestors without putting those mechanisms inside the Converge foundation.

Cargo package: converge-mnemos-knowledge. Rust library and binary names remain mnemos and mnemos-server.

Why It Exists

Converge owns governed proposal promotion. Mnemos owns memory. A formation can ask Mnemos for relevant knowledge, store durable observations, or learn from feedback while Converge still decides what becomes fact.

What Mnemos Owns

• KnowledgeBase, entries, search options, and search results.
• Local storage and hybrid vector + BM25 lexical retrieval.
• Embedding support, including OpenAI embeddings.
• Markdown and rich-media ingestion.
• Agentic memory: causal, temporal, reflexion, skill, session, online, and meta-learning modules.
• Feedback collection, replay, batch learning, and insight jobs.
• CLI and gRPC server surfaces.
• KnowledgeRetrievalSuggestor and KnowledgeStoreSuggestor.
• Typed proposal provenance through ProvenanceSource / MNEMOS_PROVENANCE.
• Suggestor-boundary tracing through mnemos.suggestor.execute spans.

Boundary

Layer	Responsibility
Converge	Context, proposals, facts, promotion, and suggestor contract.
Mnemos	Knowledge storage, recall, ingestion, memory, learning, and recall suggestors.
Products	Which knowledge stores to use, tenancy, credentials, retention, and deployment mode.

Repository Layout

crates/mnemos/
  proto/knowledge.proto
  src/core/       KnowledgeBase, entries, search
  src/embedding/  Hash and OpenAI embedding support
  src/ingest/     Markdown, rich media, routing
  src/agentic/    Causal, temporal, reflexion, skills, sessions
  src/learning/   Feedback, replay, batch jobs
  src/grpc/       gRPC server and client
  src/suggestor.rs

Usage

use mnemos::{KnowledgeBase, KnowledgeEntry};

let kb = KnowledgeBase::open("./knowledge.db").await?;
kb.add_entry(KnowledgeEntry::new(
    "Rust ownership",
    "Ownership and borrowing keep memory safe without a GC.",
))
.await?;

let results = kb.search_simple("memory safety", 5).await?;

Hybrid retrieval is available when exact terms matter as much as semantic similarity:

use mnemos::{KnowledgeBase, SearchOptions};

let kb = KnowledgeBase::open("./knowledge.db").await?;
let results = kb
    .search("BM25 RRF acronym recall", SearchOptions::new(5).hybrid(0.3))
    .await?;

The hybrid path ranks vector similarity and BM25 separately, then merges both rankings with Reciprocal Rank Fusion. RRF uses 1 / (60 + rank) with 1-based ranks, so Mnemos does not compare raw BM25 scores with vector similarity scores.

Feature Flags

• Default: cli, grpc.
• cli: enables the mnemos binary.
• grpc: enables the mnemos-server binary.
• memory-only: checks memory-only operation.

Development

just check
just check-memory
just test
just lint
just doc

Converge platform dependencies resolve from crates.io.

Project Files

• AGENTS.md - agent entrypoint and boundary rules.
• CHANGELOG.md - release notes.
• CONTRIBUTING.md - contribution guide.
• SECURITY.md - vulnerability reporting and operator notes.
• CODE_OF_CONDUCT.md - community expectations.

Status

Extracted from converge/crates/knowledge on 2026-05-05 as part of the v3.8 foundation extraction.

License

MIT - see LICENSE.