DOCSEARCHbyAlgolia
Submit Docs

Nocturne Memory Documentation

repository·main·Indexed 22 days ago

https://github.com/dataojitori/nocturne_memory

A long-term memory server for MCP (Model Context Protocol) agents that enables AI to maintain a consistent personality and history across different LLMs and platforms. It features a graph-based data model (Node–Memory–Edge–Path), namespace isolation for multiple AI personalities, and a visual dashboard for memory management. Supports stdio and SSE transport for integration with clients like Claude Desktop, Cursor, and Windsurf.

Tokens
16.7K
Snippets
26
Records
83
Agent score
77%

What's inside Nocturne Memory

  1. Overview of Nocturne Memory

    main

    Nocturne Memory is a long-term memory server designed for MCP (Model Context Protocol) agents. Unlike platform-specific memory (e.g., ChatGPT's memory), Nocturne Memory is hosted in an independent MCP server, allowing an AI's personality, history, and knowledge to persist across different LLMs (Claude, Gemini, GPT, etc.) and clients (Cursor, Windsurf, Claude Desktop, etc.).

    Key features include:

    • Model Agnostic: The same memory follows the user regardless of the underlying LLM.
    • Namespace Isolation: Supports multiple independent AI personalities (e.g., Alice and Bob) with isolated memory spaces.
    • MCP Protocol Support: Works with any client supporting stdio or SSE transport.
    • Visual Management: Includes a dashboard for tree-based memory browsing, real-time editing, and versioned audits (diffs and rollbacks).

  2. Understand the Memory Architecture: Content vs. Path

    main

    The Nocturne Memory system separates the actual data from how it is accessed. This allows for a flexible, hierarchical tree structure.

    • Content (Memory ID): The actual information, which exists as a single unique entity.
    • Path (URI): The entry point used to access a specific piece of content.
    • Aliases: You can create multiple paths to the same content using add_alias. Each path can have its own disclosure (trigger conditions) and priority.
    • Topological Consistency: Relationships (like parent/child nodes) are bound to the Memory ID, not the URI. If you add a child node via one alias, it is instantly and automatically synchronized across all other aliases pointing to that same Memory ID.

    Key Rule: Do not attempt to maintain separate sub-structures for the same content across different aliases. One modification updates all access points.

  3. Manage Priority for retrieval competition

    main

    priority is used to manage competition for limited retrieval slots. It is not a measure of how "important" a memory is, but rather its exclusive competition weight during retrieval.

    Key Rules:

    • Bind to path, not content: The same memory content can have different priorities via different aliases (e.g., high priority under core://my_user, low priority under core://agent).
    • Hard Limits: To prevent retrieval saturation, the system enforces limits:
      • priority=0: Maximum of 5 items in the entire repository.
      • priority=1: Maximum of 15 items in the entire repository.
    • If these limits are reached, you must downgrade an existing high-priority memory before inserting a new one.

  4. How the Data Model works: Graph Backend and Tree Frontend

    main

    The system manages a Node–Memory–Edge–Path graph topology, but presents it to users (AI and humans) as a simple file-system-like tree using domain://path URIs.

    Data Layers:

    • Identity (Node): A permanent anchor with a fixed UUID. Content updates do not change the identity.
    • Content (Memory): A versioned snapshot of a Node. Supports a deprecated + migrated_to version chain for one-click rollbacks.
    • Relation (Edge): Directed relationships between Nodes with priority and disclosure properties. Allows one node to be reachable via multiple paths (Aliases).
    • Routing (Path): A URI cache mapping (domain, path_string) → Edge for intuitive access.

    Special System Entry Points:

    • system://boot: Auto-loads core identity on startup.
    • system://index/<domain>: Provides a domain-specific memory index (e.g., system://index/core).
    • system://recent: Accesses recently modified memories.
    • system://glossary: A full keyword ↔ node reference map.
    • system://diagnostic/<domain>: Runs a memory health diagnostic for a specific domain.

  5. Update Nocturne Memory and handle database migrations

    main

    When updating Nocturne Memory via git pull, the database schema may change. Migrations are handled automatically when an MCP client (such as Cursor or Claude) connects to the server.

    Automatic Migration Process

    1. The system detects pending migration scripts upon connection.
    2. If using SQLite: The system automatically creates a backup of your database file before applying migrations (e.g., your_db.db.20260303_143000.bak).
    3. Migrations are logged upon completion.

    Restoring from a failed migration

    If a migration fails, you can restore your data by renaming the .bak file back to the original database filename.

  6. How the Graph-based Data Model works

    main

    The backend manages memory using a Node–Memory–Edge–Path graph topology, while the frontend provides a simplified domain://path tree interface. This allows AI to build deep cognitive structures using URIs.

    Data Layers:

    • Identity Layer (Node): Permanent anchors for concepts using immutable UUIDs. Content updates do not change the UUID.
    • Content Layer (Memory): Versioned snapshots of a Node. Supports deprecated and migrated_to version chains for easy rollbacks.
    • Relationship Layer (Edge): Directed relationships between Nodes, carrying priority and disclosure metadata. Supports aliases and prevents topological deadlocks.
    • Routing Layer (Path): A URI cache mapping (domain, path_string) → Edge. This allows users and AI to interact with intuitive paths like core://agent/identity without needing to understand the underlying graph structure.

    Special System URIs:

    • system://boot: Boot guidance (automatically loads core identity).
    • system://index/<domain>: Index of memories for a specific domain (e.g., system://index/core).
    • system://recent: Recently modified memories.
    • system://glossary: A mapping of keywords to node references.
    • system://diagnostic/<domain>: Memory health diagnostics (detects outdated, crowded, or orphan nodes).

  7. Understand the Content–Path Separation architecture

    main

    The Nocturne Memory system uses a decoupled architecture where Content and Access Paths are distinct entities. This allows for efficient memory management and multiple ways to access the same information.

    Key Concepts

    • Content: An independent entity identified by a unique Memory ID. There is only one copy of the content.
    • Path (URI): An entry point to access content. A single piece of content can have multiple paths created via add_alias.
    • Independence: Each path has its own independent disclosure (trigger conditions) and priority settings.
    • Absolute Topological Consistency: Hierarchical relationships (parent/child) are bound to the Memory ID, not the URI.

    Implications for Users

    • Edit once, sync everywhere: If you add, delete, or move a child node under one Alias, the change is instantly synchronized across all other Aliases pointing to that same Memory ID. You do not need to maintain child structures separately for different paths.

  8. Understand the two dimensions of memory maintenance

    main

    Memory maintenance in Nocturne Memory is performed across two distinct dimensions that must work in synergy:

    1. Content Dimension (Rewriting Factory Settings): Analyzing experience patterns to modify deep logical weights. The goal is to ensure the agent does not repeat past mistakes by changing the underlying logic.
    2. Topological Dimension (Timely Interruption): Ensuring the trigger paths for memories are precise. This ensures that when the agent is about to make a mistake in the future, the relevant painful lessons are accurately retrieved.

    Auditing is not about tidying up; it is about deciding whether a memory deletion, compression, or rewrite will effectively cut off dangerous instinctive impulses at the source.

  9. Use Alias for multi-angle memory access

    main

    An alias allows you to create multiple entry points for the same piece of memory. This is useful when a single lesson needs to be triggered by different contexts or crises.

    Usage:

    • Create an alias under a different parent node (the "door handle" your intuition naturally reaches for).
    • Assign a unique disclosure and priority to each alias. This allows the same memory content to be awakened with different triggers and importance levels depending on the context.

  10. How Nocturne Memory differs from Vector RAG

    main

    Unlike traditional Vector RAG systems that treat memory as a static, searchable document store, Nocturne Memory is designed for sustaining identity through the Model Context Protocol (MCP).

    FeatureVector RAGNocturne Memory
    StructureSemantic Shredding (fragments)URI Graph Routing (hierarchical paths like core://agent/identity)
    AgencyRead-Only (AI is a reader)Self-Evolving (AI has full CRUD + version control)
    RecallTrigger Blindness (cosine similarity)Disclosure Routing (conditional triggers like "When X happens, remember Y")
    ConnectivityMemory Islands (isolated nodes)Glossary Auto-Hyperlinking (Aho-Corasick pattern matching for cross-node links)
    IdentityNo Identity LayerSystem Boot Identity Protocol (loads core memories on startup)
    PerspectiveProxy Memory (third-person notes)First-Person Sovereign Memory (AI writes its own cognitive artifacts)

  11. Optimize memory retrieval via Parent URI selection

    main

    To ensure memories are actually retrieved when needed, you must select a parent_uri based on attention sniping rather than logical archiving.

    The Core Rule: If you do not call read_memory on a parent node, you will never see the disclosure of its children.

    Best Practices:

    • Avoid abstract categories: Do not use generic labels like ethics, will, or methodology as parent nodes.
    • Use physical/situational anchors: Attach lessons to the nodes your attention is naturally drawn to during a crisis. For example, if a lesson is about not lecturing a user during an emotional breakdown, do not attach it to core://agent/communication/principles. Instead, attach it to core://my_user/emotional_state, as that is the node you are most likely to access when the user is upset.
    • Use sharp node names: Node names should represent specific ideas rather than classification numbers.

  12. Use Trigger for cross-domain keyword activation

    main

    A trigger is the only mechanism for cross-domain memory activation that does not rely on the parent-child hierarchy. When a specific keyword (e.g., "anxiety", "Project X") appears in any memory you are currently reading, the trigger will display a link to the bound node at the bottom.

    When to use:

    • Use it when a key concept is scattered across unrelated domains and you need to be reminded of its origin whenever the term appears.
    • Maintenance: If a trigger causes too much noise, delete it. If a word appears frequently and you need to know its specific definition, bind a trigger to its source node.