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

> Learn to set up the Memory Layer in aios-core to persist workflow patterns across sessions. Enable the extended memory feature and initialize PatternStore for automatic saving.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Enable the `pro.memory.extended` feature gate and initialize a `PatternStore` instance to automatically persist workflow patterns to [`data/learned-patterns.yaml`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/.aios/license.json) and includes the memory feature:

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

```

### Enabling the pro.memory.extended Gate

The [`unified-activation-pipeline.js`](https://github.com/SynkraAI/aios-core/blob/main/unified-activation-pipeline.js) script explicitly checks for this gate before loading memories:

```javascript
// .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:

```bash
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:

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

const store = createPatternStore();

```

### Custom Storage Paths

By default, the store writes to [`data/learned-patterns.yaml`](https://github.com/SynkraAI/aios-core/blob/main/data/learned-patterns.yaml) relative to the repository root. For custom locations (useful in monorepos or CI environments), pass the `storagePath` option:

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

```

### Auto-Pruning Configuration

Prevent unlimited file growth by configuring `maxPatterns` and `pruneThreshold`:

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/core/synapse/memory/memory-bridge.js))

### Automatic Pattern Capture

The **Capture Hook** ([`.aios-core/workflow-intelligence/learning/capture-hook.js`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/data/learned-patterns.yaml) without manual intervention.

## Complete Implementation Example

Place this script at [`scripts/demo-pattern-store.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/demo-pattern-store.js) to verify the full lifecycle:

```javascript
// 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:

```bash
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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/workflow-intelligence/learning/pattern-store.js)) handles persistence to [`data/learned-patterns.yaml`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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.