How to Set Up the Memory Layer for Persistent Patterns Across Sessions in aios-core

Enable the pro.memory.extended feature gate and initialize a PatternStore instance to automatically persist workflow patterns to data/learned-patterns.yaml, making them available across all future activation pipeline runs.

The Memory Layer in SynkraAI/aios-core enables agents to retain learned workflow patterns, gotchas, and timeline snapshots between sessions. By configuring the Pattern Store component with the proper feature gates, you create a persistent knowledge base that the unified activation pipeline automatically loads on every run. This guide walks through the exact implementation steps required to enable cross-session pattern persistence.

Understanding the Memory Layer Architecture

The Two-Layer Storage Model

The Memory Layer consists of two logical sub-layers working in tandem:

• Claude Native Layer: Managed by the Claude Code CLI, storing files in ~/.claude/.../memory/*.md
• AIOS Framework Layer: Managed by JavaScript scripts in .aios-core/, handling Gotchas (.aios/gotchas.*), the Pattern Store (data/learned-patterns.yaml), timeline snapshots, and file-evolution logs

The Pattern Store is the primary component for persisting learned workflow patterns across sessions.

The Pattern Store Component

Located at .aios-core/workflow-intelligence/learning/pattern-store.js, the PatternStore class handles CRUD operations, auto-pruning, statistics, and caching. The factory function createPatternStore(options) returns a ready-to-use instance.

Prerequisites and Feature Gate Activation

Verifying Pro License Access

The Memory Layer is a Pro feature. The runtime checks the license before instantiating any memory providers. Ensure your license file exists at .aios/license.json and includes the memory feature:

{
  "features": ["pro.memory.extended"]
}

Enabling the pro.memory.extended Gate

The unified-activation-pipeline.js script explicitly checks for this gate before loading memories:

// .aios-core/development/scripts/unified-activation-pipeline.js
if (isProAvailable()) {
  const MemoryLoader = loadProModule('memory/memory-loader');
  const featureGate = loadProModule('license/feature-gate');
  const isMemoryEnabled = featureGate?.featureGate?.isAvailable('pro.memory.extended') ?? false;
  // ...
}

Verify the gate is active by running:

node -e "console.log(require('./.aios-core/pro/license/feature-gate').featureGate.isAvailable('pro.memory.extended'))"

This should output true. Without this gate, the pipeline skips memory loading entirely.

Configuring the Pattern Store for Persistence

Initializing the Store

While the unified-activation-pipeline initializes the store automatically, you can create custom instances for testing or CLI commands:

const { createPatternStore } = require('./.aios-core/workflow-intelligence/learning');

const store = createPatternStore();

Custom Storage Paths

By default, the store writes to data/learned-patterns.yaml relative to the repository root. For custom locations (useful in monorepos or CI environments), pass the storagePath option:

const store = createPatternStore({
  storagePath: '.aios/custom-patterns.yaml'
});

Auto-Pruning Configuration

Prevent unlimited file growth by configuring maxPatterns and pruneThreshold:

const store = createPatternStore({
  maxPatterns: 200,
  pruneThreshold: 0.8
});

The store automatically removes low-value patterns when thresholds are exceeded.

Runtime Integration with the Activation Pipeline

How the Pipeline Loads Memories

When the feature gate is active, the pipeline creates a MemoryLoader (Pro implementation) that delegates to the Pattern Store:

1. The unified-activation-pipeline.js checks isAvailable('pro.memory.extended')
2. If enabled, it loads the MemoryLoader Pro module
3. The loader calls PatternStore.load() to retrieve persisted patterns
4. Patterns are injected into the SYNAPSE engine via the Memory Bridge (core/synapse/memory/memory-bridge.js)

Automatic Pattern Capture

The Capture Hook (.aios-core/workflow-intelligence/learning/capture-hook.js) automatically calls store.save() when the engine detects successful workflow patterns. This ensures every validated pattern persists to data/learned-patterns.yaml without manual intervention.

Complete Implementation Example

Place this script at scripts/demo-pattern-store.js to verify the full lifecycle:

// scripts/demo-pattern-store.js
// Demonstrates persistent pattern storage in aios-core
const path = require('path');
const { createPatternStore } = require('../.aios-core/workflow-intelligence/learning');

// 1. Initialise (default storage = data/learned-patterns.yaml)
const store = createPatternStore();

// 2. Create a sample pattern
const sample = {
  sequence: ['npm install', 'npm run lint', 'npm test'],
  successRate: 0.92,
  status: 'active',
};

// 3. Persist it
const result = store.save(sample);
console.log('Save result:', result.action, result.pattern.id ?? '(no id)');

// 4. Load all patterns
const all = store.load();
console.log(`Loaded ${all.patterns.length} pattern(s) from ${store.storagePath}`);

// 5. Find similar patterns
const similar = store.findSimilar(['npm install', 'npm test']);
console.log('Similar patterns found:', similar.map(p => p.id));

// 6. Show stats
console.log('Store stats:', store.getStats());

Execute with:

node scripts/demo-pattern-store.js

Summary

• The Memory Layer requires the pro.memory.extended feature gate active in your license configuration.
• PatternStore (.aios-core/workflow-intelligence/learning/pattern-store.js) handles persistence to data/learned-patterns.yaml by default.
• The unified activation pipeline automatically loads memories when the gate is enabled, injecting hints into the SYNAPSE engine.
• Use createPatternStore() to customize storage paths, enable auto-pruning with maxPatterns, or manually manage patterns in CLI tools.

Frequently Asked Questions

What happens if the pro.memory.extended gate is not enabled?

If the feature gate is inactive, the unified-activation-pipeline.js skips the MemoryLoader initialization entirely. The system runs in stateless mode—patterns learned during a session remain in memory only and disappear when the process exits. No errors are thrown, but no persistence occurs.

Can I use a custom storage location for learned patterns?

Yes. Pass the storagePath option to createPatternStore() to override the default data/learned-patterns.yaml location. This is particularly useful in monorepos where you want project-specific pattern files or in CI environments where the repository root is read-only.

How does the system prevent the pattern file from growing indefinitely?

The PatternStore implements automatic pruning based on the maxPatterns and pruneThreshold configuration options. When the total pattern count exceeds maxPatterns, the store removes low-success-rate entries falling below the pruneThreshold (default 0.8). This keeps learned-patterns.yaml performant and prevents storage bloat.

Is the Memory Layer compatible with CI/CD environments?

Yes, provided the CI runner has access to the Pro license file and the pro.memory.extended gate. For ephemeral CI runners, mount a persistent volume to data/learned-patterns.yaml (or your custom storagePath) to ensure patterns survive job restarts. The Pattern Store works identically in headless environments as it does in local development.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}