Module filesystem 

Filesystem-based persistence backend.

A fallback backend that stores memories as individual JSON files. Useful for testing and environments without git.

Security

This module includes protections against filesystem-based attacks:

• Path traversal: Memory IDs are validated to prevent directory escape
• File size limits: Maximum file size enforced to prevent memory exhaustion
• Encryption at rest: Optional AES-256-GCM encryption (CRIT-005)

Encryption

When the encryption feature is enabled and SUBCOG_ENCRYPTION_KEY is set, all memory files are encrypted with AES-256-GCM before writing to disk.

# Generate a key
openssl rand -base64 32

# Enable encryption
export SUBCOG_ENCRYPTION_KEY="your-base64-encoded-key"

Structs

FilesystemBackend

Filesystem-based persistence backend.

StoredMemory 🔒

Serializable memory format for filesystem storage.

Constants

MAX_FILE_SIZE 🔒

Maximum file size for memory files (1MB). Prevents memory exhaustion from maliciously large files.

Functions

extract_memory_id_from_path 🔒

Extracts a memory ID from a JSON file path.