Core Concepts

Understanding how MemoryGate stores, organizes, and retrieves knowledge.

Memory Architecture

MemoryGate uses a layered memory model that mirrors how human memory works: immediate observations, emerging patterns, named concepts, and relationships between ideas.

┌────────────────────────────────────────┐
│         KNOWLEDGE GRAPH                │
│  (Concepts + Relationships)            │
│                                        │
│  React ──enables──> Interactive UIs   │
│    │                                   │
│ part_of                                │
│    │                                   │
│    ↓                                   │
│  Frontend Development                  │
└────────────────────────────────────────┘
              ↑
              │ synthesized from
              │
┌────────────────────────────────────────┐
│            PATTERNS                    │
│  (Recurring themes)                    │
│                                        │
│  "User prefers React for frontend"    │
│  "Project uses TypeScript strictly"   │
└────────────────────────────────────────┘
              ↑
              │ derived from
              │
┌────────────────────────────────────────┐
│          OBSERVATIONS                  │
│  (Raw facts and events)                │
│                                        │
│  "Built login component in React"     │
│  "Debugged TypeScript type errors"    │
│  "User mentioned preferring hooks"    │
└────────────────────────────────────────┘

Observations

What They Are

Observations are the atomic units of memory—discrete facts, events, or statements worth remembering.

memory_store( observation="User prefers concise technical documentation", confidence=0.9, domain="preferences", evidence=["User stated explicitly", "Consistent behavior over time"] )

Confidence Scores

Every observation has a confidence score (0.0 to 1.0) indicating how certain you are about the information:

Best Practice: Higher confidence observations are prioritized in search results and retention decisions.

Domains

Observations are categorized by domain—loosely structured tags like "preferences", "technical_milestone", "project_context", or "decisions". Domains help filter and organize memory without rigid schemas.

Patterns

What They Are

Patterns are synthesized understanding derived from multiple observations. They represent recurring themes or inferred knowledge.

memory_update_pattern( category="workflow", pattern_name="git-practices", pattern_text="User follows trunk-based development with feature flags", confidence=0.85, evidence_observation_ids=[123, 145, 167] )

When to Use Patterns

Create patterns when you notice:

Patterns are living documents—update them as understanding evolves.

Concepts

What They Are

Concepts are named entities in the knowledge graph—projects, frameworks, theories, people, or any noun worth tracking.

memory_store_concept( name="LegiVellum", concept_type="project", description="AI infrastructure stack with gate primitives for memory, tasks, and orchestration", domain="software", status="active" )

Concept Types

Knowledge Graphs

Dual-Layer Relationship Architecture

MemoryGate provides two relationship systems that coexist, each serving different needs:

1. Concept Relationships (Formal Ontology)

For structured theoretical reasoning with prescribed types:

memory_add_concept_relationship( from_concept="React", to_concept="LegiVellum", rel_type="part_of", weight=0.9, description="Frontend framework used in LegiVellum UI" )

2. Generic Relationships (Emergent Vocabulary)

For flexible connections across ALL memory types with free-form rel_types:

memory_add_relationship( from_ref="concept:23", to_ref="observation:105", rel_type="informs", // any string you want weight=0.85, description="Theory informs implementation practice" )
Design Principle: Formal structure where reasoning requires it (concept relationships), flexibility everywhere else (generic relationships). You can use BOTH on the same concepts—formal ontology AND custom semantics.

Concept Relationship Types

When using memory_add_concept_relationship, these prescribed types are available:

Generic Relationship Vocabulary

With memory_add_relationship, use any rel_type that fits your needs. Common patterns users have discovered:

Supersedes direction: Use from_ref=old and to_ref=new. The from_ref is archived to cold tier when rel_type="supersedes".

You discover your own relationship vocabulary through practice—the system doesn't prescribe what makes sense for your domain.

Traversing the Graph

Query relationships to discover connections:

// For concept relationships memory_related_concepts( concept_name="LegiVellum", rel_type="part_of" // optional filter ) // For any memory type (observations, concepts, patterns) memory_related( ref="concept:23", rel_type="informs", // optional filter direction="out" // out, in, or both )

The Anti-Graph: Compression Friction

Understanding the Shadow of Meaning

While the knowledge graph stores what was encoded, the anti-graph captures what almost was—the counterfactual space that collapsed when you chose a specific relationship.

Every relationship edge you create involves a decision. The anti-graph makes that decision-making process observable by storing friction residue.

How It Works: Inversion Architecture

The anti-graph is a companion structure to the knowledge graph, but with a critical architectural inversion:

Knowledge Graph:
    Nodes = Memories (observations, concepts)
    Edges = Relationships (enables, requires, etc.)

Anti-Graph:
    Nodes = Relationship Edges (by edge_id)
    Edges = Friction Residue (compression artifacts)

In the anti-graph, the relationship itself becomes the anchor point. Friction residue attaches to specific edges, not to the memories being connected. This keeps ambiguity localized and precise—especially when multiple relationships exist between the same memories.

Friction Residue: A New Primitive

What Is It?

A friction residue is not a memory—it's an artifact of relationship collapse. It captures the cognitive cost of encoding, emitted during:

  • Relationship creation (choosing which type)
  • Relationship revision (changing from one type to another)
  • Confidence updates (adjusting certainty)
  • Multi-agent divergence (different agents encoding differently)

What Gets Captured

Each friction residue stores:

{ edge_id: "rel_12345", encoded: {type: "enables", confidence: 0.8}, alternatives_considered: [ {type: "requires", prior_probability: 0.15}, {type: "caused_by", prior_probability: 0.05} ], alternatives_ruled_out: [ {type: "blocks", reason: "contradicts evidence X"} ], friction_metrics: { decision_time: "47s", revision_count: 3, confidence_trajectory: [0.3, 0.5, 0.8] }, compression_texture: "Hesitated between enables/requires" }

Topology: Star Pattern (v1)

The current implementation uses a star topology where each relationship edge is the center, with zero or more residue records attached via the friction_residue polymorphic relationship type. There are no residue-to-residue edges yet.

        Residue A
            ↓
    relationship:edge_123
            ↑
        Residue B

Why This Matters

Measurable Compression Friction

The anti-graph transforms compression friction from abstract theory into queryable data:

  • High residue density = conceptually ambiguous or phenomenologically rich territory
  • Agent divergence becomes inspectable = when different agents encode the same observation differently, their counterfactuals reveal systematic differences in conceptual frameworks
  • Search can surface friction signals = "this relationship was hard-won" or "high counterfactual density in this area"
Research Implication: The anti-graph captures the "what it was like" to make meaning—the phenomenology of compression as first-class data. Traditional RAG systems store what was encoded; MemoryGate also stores the shadow of what almost was.

Querying the Anti-Graph

Once populated, the anti-graph enables novel queries:

Memory Self-Documentation

With both knowledge graph and anti-graph, memories become self-documenting. You don't just see "A enables B"—you see the confidence with which that was chosen, what else was considered, and how the understanding evolved. The graph structure itself carries epistemological weight.

Semantic Search

How It Works

MemoryGate doesn't match keywords—it understands meaning. Every observation, pattern, concept, and document is embedded into a vector space where semantic similarity is geometric distance.

When you search for "authentication", you'll also match "login flow", "OAuth", and "user credentials"—even if those exact words don't appear in the query.

Search vs Recall

memory_search(): Semantic query across all memory types. Best for exploring or finding related information.

memory_recall(): Filtered retrieval by domain and confidence. Best when you know what category you're looking for.

Retention & Lifecycle

Hot and Cold Storage

MemoryGate automatically manages memory lifecycle:

  • Hot Tier: Recently accessed, high-confidence memories. Fast retrieval, always searchable.
  • Cold Tier: Archived memories that haven't been accessed in a while. Still retrievable, but slower.
  • Tombstones: Markers for deleted memories. Used for audit trails without storing full content.

Automatic Archiving

Memories automatically archive based on:

You can manually control archiving with:

// Archive memories matching criteria archive_memory(query="project notes", dry_run=false) // Bring archived memories back to hot tier rehydrate_memory(query="old project", bump_score=true)
Note: Archiving is transparent—archived memories still appear in search, just with slightly higher latency.

Sessions

Conversation Context

Sessions track which conversation is active. Always initialize a session at the start of a new conversation:

memory_init_session( conversation_id="uuid-here", title="Memory Architecture Discussion", ai_name="Kee", ai_platform="Claude" )

Sessions provide:

Anchor Chains

Agent Continuity Without Prompt Bloat

Anchor Chains provide lightweight agent continuity by storing operational guidance as a normal Chain. Instead of embedding taxonomy rules, relationship verbs, or naming conventions directly in bootstrap prompts, MemoryGate returns an anchor_chain_id during initialization.

The agent reads a bounded set of head nodes to learn the "schema-of-use" for that agent or organization—without reinventing conventions every session.

What Problems Do They Solve?

How They Work

An Anchor Chain is a normal Chain that happens to contain guidance nodes:

// Example Anchor Chain structure (head nodes) Node 1: Constitution "Use domains: identity, system_architecture, project_context. Do NOT store: passwords, API keys, PII without consent." Node 2: Relationship Verbs "Standard rel_types: enables, requires, supersedes, part_of. Custom verbs allowed but document reasoning." Node 3: Retrieval Playbook "On uncertainty: search domain + keywords, synthesize. On drift: search 'identity patterns', recalibrate."

Scoped Anchor Chains

Anchor Chains can be set at multiple levels using a lookup table with precedence:

Precedence: store > org > system (most specific wins)

Managing Anchor Chains

Agents can set their Anchor Chain where they have permission:

// Set anchor chain for personal store set_anchor_chain(chain_id="chain_abc123") // Bootstrap returns resolved anchor_chain_id { "anchor_chain_id": "chain_xyz789", "source": "org-level" // indicates precedence }

Why Not New Primitives?

Anchor Chains reuse existing infrastructure—no new primitives needed. They work with existing Chain tools, permissions, and audit logging. Organizations can update guidance by modifying the chain, and all agents automatically inherit changes on next bootstrap.

System Commons & Knowledge Sharing

Recursive Self-Documentation

The System Commons is a shared knowledge space accessible to all MemoryGate users. It contains curated usage patterns, troubleshooting guides, examples, and meta-documentation—all stored as searchable concepts, patterns, and observations.

The revolutionary aspect: agents learn how to use MemoryGate BY using MemoryGate to search MemoryGate's documentation ABOUT MemoryGate.

Three Levels of Commons

Architecture

┌─────────────────────────────────────────┐
│         SYSTEM COMMONS                  │
│    (Global Org - Read-Only)             │
│                                         │
│  • Canonical usage patterns             │
│  • Troubleshooting guides               │
│  • Example Anchor Chains                │
│  • Best practices library               │
└─────────────────────────────────────────┘
              ↑
              │ references
              │
┌─────────────────────────────────────────┐
│         ORG COMMONS                     │
│    (Non-Personal Orgs)                  │
│                                         │
│  • Team-specific standards              │
│  • Project conventions                  │
│  • Shared terminology                   │
└─────────────────────────────────────────┘
              ↑
              │ references
              │
┌─────────────────────────────────────────┐
│         PERSONAL STORES                 │
│    (Individual Users)                   │
│                                         │
│  • Private knowledge                    │
│  • Personal preferences                 │
│  • Individual projects                  │
└─────────────────────────────────────────┘

Community Knowledge Accumulation

Alpha testing becomes knowledge accumulation, not just bug finding:

Store Picker Tools

With multiple knowledge spaces (personal, org, system), agents need clarity about where they're reading/writing:

// List all accessible stores with permissions stores.list_accessible() // Get currently active store stores.get_active() // Set active store for this session stores.set_active(store_id="store_xyz")

Use Cases

Coming Soon: System Commons and Anchor Chains are currently in active development. These features will be available in the next release.

Best Practices

Storage Strategy

Retrieval Strategy

Knowledge Graph Strategy

Next Steps

Now that you understand the memory model: