Configuration

Python configuration

All parameters are set via CognitiveMemoryConfig:

from cognitive_memory import CognitiveMemoryConfig

config = CognitiveMemoryConfig(
    # ... parameters
)
mem = CognitiveMemory(config=config)

Decay parameters

Parameter	Type	Default	Description
`faint_threshold`	`float`	`0.15`	Retention below which a memory is “faint”
`decay_model`	`str`	`"exponential"`	Decay curve: `"exponential"` or `"power"`
`power_decay_gamma`	`float`	`1.4427`	Gamma exponent for power-law decay (only used when `decay_model="power"`)

The base decay rates and floors are defined as module-level constants:

Constant	Value	Description
`BASE_DECAY_RATES[EPISODIC]`	45.0	Episodic decay rate (days)
`BASE_DECAY_RATES[SEMANTIC]`	120.0	Semantic decay rate (days)
`BASE_DECAY_RATES[PROCEDURAL]`	infinity	Procedural never decays
`BASE_DECAY_RATES[CORE]`	120.0	Core decay rate (days)
`DECAY_FLOORS["core"]`	0.60	Core retention floor
`DECAY_FLOORS["regular"]`	0.02	Regular retention floor

Hybrid search

Parameter	Type	Default	Description
`hybrid_search`	`bool`	`False`	Enable hybrid (semantic + lexical) search
`k_sparse`	`int`	`30`	Number of lexical candidates for hybrid search

Validity

Parameter	Type	Default	Description
`filter_expired_transients`	`bool`	`True`	Filter out transient memories past their expiry
`include_expired_in_deep_recall`	`bool`	`True`	Include expired transients when deep recall is enabled

Graph

Parameter	Type	Default	Description
`graph_expansion_hops`	`int`	`1`	Number of association hops for graph-based retrieval expansion
`bridge_discovery`	`bool`	`False`	Enable discovery of bridge paths between memories
`max_bridge_paths`	`int`	`3`	Maximum number of bridge paths to return
`min_bridge_edge_weight`	`float`	`0.3`	Minimum edge weight for bridge path traversal

Retrieval scoring

Parameter	Type	Default	Description
`retrieval_score_exponent`	`float`	`0.3`	Alpha in `score = sim * R^alpha`. Lower values ignore decay more.

Retrieval boosting

Parameter	Type	Default	Description
`direct_boost`	`float`	`0.1`	Stability increase for direct retrieval
`associative_boost`	`float`	`0.03`	Stability increase for associative retrieval
`max_spaced_rep_multiplier`	`float`	`2.0`	Cap on spaced repetition factor
`spaced_rep_interval_days`	`float`	`7.0`	Days for 1x spaced rep factor

Core promotion

Parameter	Type	Default	Description
`core_access_threshold`	`int`	`10`	Min retrievals for promotion
`core_stability_threshold`	`float`	`0.85`	Min stability for promotion
`core_session_threshold`	`int`	`3`	Min distinct sessions for promotion

Associations

Parameter	Type	Default	Description
`association_strengthen_amount`	`float`	`0.1`	Weight increase per co-retrieval
`association_retrieval_threshold`	`float`	`0.3`	Min weight to activate association
`association_decay_constant_days`	`float`	`90.0`	Exponential decay time constant

Consolidation

Parameter	Type	Default	Description
`consolidation_retention_threshold`	`float`	`0.20`	Retention below which memories are consolidation candidates
`consolidation_group_size`	`int`	`5`	Min group size for consolidation
`consolidation_similarity_threshold`	`float`	`0.70`	Min similarity for grouping

Tiered storage

Parameter	Type	Default	Description
`cold_migration_days`	`int`	`7`	Days at floor before cold migration
`cold_storage_ttl_days`	`int`	`180`	Days in cold before stub conversion

Deep recall

Parameter	Type	Default	Description
`deep_recall_penalty`	`float`	`0.5`	Score multiplier for superseded memories

Ingestion

Parameter	Type	Default	Description
`run_maintenance_during_ingestion`	`bool`	`True`	Run tick() every 5 ingestions

Reranking

Parameter	Type	Default	Description
`rerank_enabled`	`bool`	`False`	Enable LLM reranking of top candidates
`k_rerank`	`int`	`10`	Number of top candidates to send to LLM for reranking
`rerank_model`	`str \| None`	`None`	Model for reranking; defaults to extraction model if not set

Extraction

Parameter	Type	Default	Description
`extraction_mode`	`str`	`"semantic"`	`"raw"` (verbatim turns), `"semantic"` (LLM facts), or `"hybrid"` (both)
`extraction_model`	`str`	`"gpt-4o-mini"`	LLM for memory extraction
`custom_extraction_instructions`	`str \| None`	`None`	Prepend to extraction prompt

Models

Parameter	Type	Default	Description
`embedding_model`	`str`	`"text-embedding-3-small"`	Embedding model
`embedding_dimensions`	`int`	`1536`	Embedding vector dimensions

TypeScript configuration

const mem = new CognitiveMemory({
    adapter: new InMemoryAdapter(),
    embeddingProvider: myEmbedder,
    userId: "user-123",
    config: {
        // ... parameters
    },
});

Available parameters

The TypeScript SDK exposes the same parameters as Python, using camelCase naming. Key parameters:

Parameter	Type	Default	Description
`defaultImportance`	`number`	`0.5`	Default importance for new memories
`defaultStability`	`number`	`0.3`	Default stability for new memories
`minRetention`	`number`	`0.2`	Minimum retention for retrieval results
`faintThreshold`	`number`	`0.15`	Retention below which memories are “faint”
`decayRates.episodic`	`number`	`45`	Episodic decay rate (days)
`decayRates.semantic`	`number`	`120`	Semantic decay rate (days)
`decayRates.procedural`	`number`	`Infinity`	Procedural decay rate (days)
`decayRates.core`	`number`	`120`	Core decay rate (days)
`retrievalScoreExponent`	`number`	`0.3`	Alpha in `score = sim * R^alpha`
`directBoost`	`number`	`0.1`	Stability increase for direct retrieval
`associativeBoost`	`number`	`0.03`	Stability increase for associative retrieval
`coreAccessThreshold`	`number`	`10`	Min retrievals for core promotion
`coreStabilityThreshold`	`number`	`0.85`	Min stability for core promotion
`coreSessionThreshold`	`number`	`3`	Min distinct sessions for core promotion
`consolidationRetentionThreshold`	`number`	`0.20`	Retention below which memories are consolidation candidates
`consolidationGroupSize`	`number`	`5`	Min group size for consolidation
`coldMigrationDays`	`number`	`7`	Days at floor before cold migration
`coldStorageTtlDays`	`number`	`180`	Days in cold before stub conversion
`deepRecallPenalty`	`number`	`0.5`	Score multiplier for superseded memories
`decayModel`	`string`	`"exponential"`	Decay curve: `"exponential"` or `"power"`
`powerDecayGamma`	`number`	`1.4427`	Gamma exponent for power-law decay
`hybridSearch`	`boolean`	`false`	Enable hybrid (semantic + lexical) search
`kSparse`	`number`	`30`	Number of lexical candidates for hybrid search
`filterExpiredTransients`	`boolean`	`true`	Filter out transient memories past their expiry
`includeExpiredInDeepRecall`	`boolean`	`true`	Include expired transients when deep recall is enabled
`graphExpansionHops`	`number`	`1`	Number of association hops for graph-based retrieval expansion
`bridgeDiscovery`	`boolean`	`false`	Enable discovery of bridge paths between memories
`maxBridgePaths`	`number`	`3`	Maximum number of bridge paths to return
`minBridgeEdgeWeight`	`number`	`0.3`	Minimum edge weight for bridge path traversal
`rerankEnabled`	`boolean`	`false`	Enable LLM reranking of top candidates
`kRerank`	`number`	`10`	Number of top candidates to send to LLM for reranking
`rerankModel`	`string \| null`	`null`	Model for reranking; defaults to extraction model if not set
`extractionMode`	`string`	`"semantic"`	`"raw"`, `"semantic"`, or `"hybrid"`
`extractionModel`	`string`	`"gpt-4o-mini"`	LLM for extraction
`customExtractionInstructions`	`string \| null`	`null`	Prepend to extraction prompt

Full Python example

config = CognitiveMemoryConfig(
    # Decay
    faint_threshold=0.15,
    decay_model="exponential",
    power_decay_gamma=1.4427,

    # Hybrid search
    hybrid_search=False,
    k_sparse=30,

    # Validity
    filter_expired_transients=True,
    include_expired_in_deep_recall=True,

    # Graph
    graph_expansion_hops=1,
    bridge_discovery=False,
    max_bridge_paths=3,
    min_bridge_edge_weight=0.3,

    # Retrieval scoring
    retrieval_score_exponent=0.3,

    # Retrieval boosting
    direct_boost=0.1,
    associative_boost=0.03,
    max_spaced_rep_multiplier=2.0,
    spaced_rep_interval_days=7.0,

    # Core promotion
    core_access_threshold=10,
    core_stability_threshold=0.85,
    core_session_threshold=3,

    # Associations
    association_strengthen_amount=0.1,
    association_retrieval_threshold=0.3,
    association_decay_constant_days=90.0,

    # Consolidation
    consolidation_retention_threshold=0.20,
    consolidation_group_size=5,
    consolidation_similarity_threshold=0.70,

    # Tiered storage
    cold_migration_days=7,
    cold_storage_ttl_days=180,

    # Deep recall
    deep_recall_penalty=0.5,

    # Ingestion
    run_maintenance_during_ingestion=True,

    # Extraction
    extraction_mode="semantic",
    extraction_model="gpt-4o-mini",
    custom_extraction_instructions=None,

    # Reranking
    rerank_enabled=False,
    k_rerank=10,
    rerank_model=None,

    # Models
    embedding_model="text-embedding-3-small",
    embedding_dimensions=1536,
)

Tuning guidelines

See the Tuning guide for detailed advice on adjusting these parameters for your workload.

Key interactions to be aware of:

retrieval_score_exponent and direct_boost interact: higher alpha makes boosting more impactful
consolidation_retention_threshold and cold_migration_days together control when memories leave hot storage
core_access_threshold and core_stability_threshold create a compound requirement: lowering one doesn’t help if the other is too high