DOCSEARCHbyAlgolia
Submit Docs

mnemon

repository·master·Indexed 18 days ago

https://github.com/mnemon-dev/mnemon

An LLM-supervised persistent memory system for AI agents featuring a four-graph knowledge store (temporal, entity, causal, and semantic). It allows agents to maintain cross-session memory using the host LLM as a supervisor for memory management via an intent-native protocol with primitives for remember, link, and recall. Includes Mnemon Harness R7, an experimental local-first authority for durable Agent events, and supports integration with various AI IDEs and agents such as Claude Code, Cursor, and Pi.

Tokens
64.2K
Snippets
157
Records
261
Agent score
64%

What's inside mnemon

  1. What is Mnemon Harness?

    master

    Mnemon Harness is an experimental R7 implementation of mnemond, serving as a local-first authority for durable Agent events. It is designed to be isolated from the released root mnemon command and its Memory behavior.

    It follows a specific Agent-facing model: View -> Intent -> Receipt -> View'

    Key components include:

    • mnemon-harness: Sets up the Pi integration and acts as the private Agent terminal.
    • mnemond: Manages local admission, Events, Handlings, References, Artifacts, and Receipts.
    • Peer links (optional): Allows moving authenticated candidates between independent mnemond nodes, where every receiver re-admits them locally.

  2. Understand the R5 Core Contract status

    master

    The R5 Core Contract is RETIRED and has been superseded by the R7 Core Contract.

    Important for developers:

    • R5 no longer constrains the active Harness.
    • The R5 evidence ledger stops growing at retirement.
    • The current repository tree may not be able to build or run R5; it is preserved only as a historical record of the first complete R5 collaboration slice.
    • If you are looking for the current implementation and requirements, refer to r7-core-contract.md.

  3. Understand R7 T0 guarantees and limitations

    master

    R7 T0 is an opportunistic, Hook-driven contract. It is designed for explicit action and durable responsibility, but it has specific boundaries.

    What is Guaranteed

    • Explicit action: Operations are triggered by specific events.
    • Durable responsibility: The contract tracks obligations.
    • Idempotent submission: Repeated submissions are handled safely.
    • Completion evidence floor: Adherence to the P-10 requirement (Artifacts for completed status).
    • Receipt-based completion: Prevents protocol false completion.

    What is NOT Guaranteed

    • Independent review: Self-review is structurally possible (the source and target of an Event can be the same AgentPrincipal).
    • Managed wake: T0 does not launch, wake, or retry Agent Runtime processes in the background. A pending Handling waits for the next eligible interactive boundary.
    • Objective correctness: It does not guarantee the business correctness of results.
    • Process-level attestation: It does not distinguish the installed Hook callback from other same-UID local processes.

  4. Identify Mnemon's Core Engineering Choices

    master

    Mnemon bridges theoretical LLM orchestration paradigms with production-ready engineering. Key design choices include:

    LayerChoice
    ParadigmThe host LLM orchestrates, not an embedded model
    Protocol semanticsIntent-native (LLM expresses what it needs, not how to get it)
    MethodologyFour-graph architecture (temporal, entity, causal, semantic)
    Protocol algebraremember, link, and recall as universal primitives
    Protocol InterfaceCLI commands + structured JSON (avoids code generation/sandboxes)
    LifecycleHook-driven: remember $\rightarrow$ diff $\rightarrow$ link $\rightarrow$ gc
    DistributionSingle Go binary, zero dependencies

  5. Understand the Mnemon Go Engineering Standard

    master

    The Mnemon Go Engineering Standard is a project-wide contract for hand-written Go code in the root product and experimental Harness. It prioritizes correctness and safety over clarity, simplicity, reuse, and source-line reduction.

    Key principles include:

    • Structured Authority: Deterministic Go code owns identities, state transitions, and persistence. Natural-language content from models is treated as untrusted, opaque, and bounded data.
    • Ownership: Every package must have one coherent reason to change, and every piece of mutable state must have one identifiable owner.
    • Explicit Control Flow: Guard clauses, error checks, and fail-closed decisions must remain explicit. Removing if statements is not a goal.
    • Abstraction Criteria: An abstraction is only valuable if it reduces independent sources of truth, invalid state combinations, change amplification, or ownership ambiguity.

  6. Overview of the Mnemon Core Architecture

    master

    Mnemon is a persistent memory system for LLM agents implemented as a single Go binary with a SQLite backend (using WAL mode). It organizes memory into a four-graph knowledge structure.

    System Layers

    1. CLI Layer: The interface used by the host LLM to trigger memory actions.
    2. Engine: The core logic that processes commands and manages the graph.
    3. Storage: A SQLite database providing persistent, isolated storage via named stores.

    The Four-Graph Model (MAGMA)

    Memory is structured using four types of edges to provide deep context:

    • Temporal: Tracks when events occurred.
    • Entity: Connects related entities.
    • Causal: Captures cause-and-effect relationships.
    • Semantic: Captures meaning-based associations.

  7. What is an Edge (Relationship)?

    master

    An Edge represents a relationship between two Insights, connecting a source_id to a target_id. Edges are the foundation of the MAGMA four-graph model.

    Edge Properties

    • edge_type: Defines the nature of the relationship. Supported types are temporal, semantic, causal, and entity.
    • weight: A value between 0.0 and 1.0 representing the strength of the connection.
    • metadata: A JSON object for additional context (e.g., {"sub_type": "backbone"}).

  8. What is an Insight (Memory Node)?

    master

    An Insight is the fundamental unit of memory in Mnemon. It represents an independent piece of knowledge. Each insight contains metadata such as a unique UUID, content, category, importance, tags, and entities.

    Categories

    Insights are categorized into six types to distinguish the nature of the memory:

    CategoryMeaningExample
    preferenceUser preference"Prefers communicating in Chinese"
    decisionArchitectural/technical decision"Chose SQLite over PostgreSQL"
    factObjective fact"API rate limit is 100 req/s"
    insightReasoning conclusion"Beam search is more suitable than full BFS for..."
    contextProject context"Phase 3 completed, 118 tests passing"
    generalGeneralContent that doesn't fit the above categories

    Importance Levels

    Importance ranges from 1 to 5 and directly affects retrieval ranking and the garbage collection (GC) lifecycle:

    • 5: Critical decision; never automatically cleaned up.
    • 4: Important fact; immune to auto-pruning.
    • 3: Standard memory.
    • 2: Low priority.
    • 1: Temporary information; the first to be cleaned up during GC.

  9. What is Mnemon and how does it differ from other memory solutions?

    master

    Mnemon is a standalone memory engine designed to solve the 'amnesia' problem in LLM agents (context compression loss, cross-session forgetting, and long-session decay). Unlike SDKs or plugins that are embedded within an agent framework, Mnemon operates as an independent entity that can be called via the command line by any LLM CLI (such as Claude Code, Cursor, or others).

    Key architectural differentiators include:

    • Standalone Binary: It does not require being embedded in a specific call chain.
    • MAGMA Four-Graph: Uses a specialized graph structure rather than simple vector similarity or flat files.
    • Intent-adaptive Retrieval: Uses multi-signal fusion instead of just vector similarity.
    • Advanced Lifecycle Management: Implements EI decay, Garbage Collection (GC), and immunity mechanisms rather than simple TTL-based expiration.
    • Zero External Dependencies: Does not require external databases or specific LLM API keys to function as a memory engine.

  10. The mnemond Protocol Loop

    master

    The mnemond protocol provides a durable, bounded action view for runtimes. It follows a strict single-loop lifecycle:

    View -> Intent -> Receipt

    Key constraints:

    • One turn, one action: One eligible Host turn owns exactly one Attachment and can commit at most one accepted Intent.
    • No manual lifecycle management: Do not invoke hook attach or hook end; these are managed by the installed Runtime extension.
    • Post-acceptance rule: After an accepted Receipt, perform no further mnemond mutations in that same turn.
    • Error handling: A rejected Receipt creates no Effect; use the provided bounded diagnostic to amend your approach or defer.
    View -> Intent -> Receipt

  11. Architectural design patterns for continuity and authority

    master

    The Mnemon architecture utilizes several high-complexity patterns to ensure continuity, authority, and verifiable state. These patterns are considered justified for high-risk operations:

    • Identity & Binding: Signed Channel rosters and origin binding; canonical Event/publication identity.
    • Integrity: Operation key plus request digest; content-addressed Artifact verification.
    • Atomicity: Atomic Event/Work/Handling/publication commits.
    • Lifecycle & Ownership: Claim lease, owner fence, and terminal receipt; bounded network frames, queues, and worker ownership.
    • Persistence & Isolation: Durable Inbox (separating delivery from Agent availability); independent task oracle and isolated Node state.

  12. Understand the boundaries of Mnemon Harness R7

    master

    It is important to distinguish what Mnemon Harness R7 is and is not to avoid architectural misuse:

    What it is NOT:

    • An Agent Runtime, scheduler, or workflow engine.
    • A Channel service or Teamwork registry.
    • A semantic schema loader or global truth store.

    Key Constraints:

    • Closed Machine Consequences: While Event kind and first-publish Reference keys are open labels, the actual machine consequences are a closed set enforced by local admission.
    • Security/Privacy: Pi provider and model configuration (including credentials) must remain Pi-owned. They must never enter Harness state, Events, logs, or evidence.
    • Independence: The root mnemon binary, mnemon setup, and Legacy Memory do not depend on the Harness.