Reference

Configuration reference

Every MemoryConfig field and default in outhad-contextkitai 0.1.4, generated from the release on PyPI.

Every field and default below is read from outhad-contextkitai 0.1.4 on PyPI and regenerated after each release. Pass any of these to Memory.from_config({...}) as nested dictionaries.

Memory

`MemoryConfig`

Field	Type	Default	Description
`vector_store`	`VectorStoreConfig`	`VectorStoreConfig()`	Configuration for the vector store
`llm`	`LlmConfig`	`LlmConfig()`	Configuration for the language model
`embedder`	`EmbedderConfig`	`EmbedderConfig()`	Configuration for the embedding model
`history_db_path`	`str`	`os.path.join(outhad_contextkit_dir, 'history.db')`	Path to the history database
`graph_store`	`GraphStoreConfig`	`GraphStoreConfig()`	Configuration for the graph
`tcmgm`	`TCMGMConfig`	`TCMGMConfig()`	TCMGM (episodic memory: dated events and cause → effect links). Set up whenever graph_store is configured; ignored without one.
`version`	`str`	`'v1.1'`	The version of the API
`custom_fact_extraction_prompt`	`Optional[str]`	`None`	Custom prompt for the fact extraction
`custom_update_memory_prompt`	`Optional[str]`	`None`	Custom prompt for the update memory
`ppmf`	`PPMFConfig`	`PPMFConfig()`	Privacy-Preserving Memory Firewall configuration
`chunking`	`ChunkingConfig`	`ChunkingConfig()`	Configuration for document chunking (optional feature)
`context_graph`	`ContextGraphConfig`	`ContextGraphConfig()`	Context-Graph Layer (CGL) configuration. Defaults to disabled; behaviour is byte-identical to legacy Memory when `enabled=False`.
`mspr`	`MSPRConfig`	`MSPRConfig()`	Multi-Stage Personalized Retrieval (MSPR) configuration. Opt-in; behaviour is byte-identical to pre-MSPR Memory when `enabled=False`.
`tenant`	`TenantConfig`	`TenantConfig()`	Tenant + sub-tenant routing configuration. Opt-in; behaviour is byte-identical when `enabled=False` (default). See doc_extra/TENANT_AND_DECAY/IMPLEMENTATION_GUIDE.md.
`decay_v2`	`DecayV2Config`	`DecayV2Config()`	Time-aware decay + immutable versioning (Part D). Opt-in; byte-identical when `enabled=False` (default). Layers decay_score, periodic scheduler, versioned updates, reference tracker, cold archival on top of CGL.
`state_store`	`StateStoreConfig`	`StateStoreConfig()`	Optional Postgres database for the opt-in layers' state (context graph, MSPR stores, cold storage). Default: local disk.

LLM

Set under llm in the config.

`LlmConfig`

Field	Type	Default	Description
`provider`	`str`	`'openai'`	Provider of the LLM (e.g., 'ollama', 'openai')
`config`	`Optional[dict]`	`{}`	Configuration for the specific LLM

Embedder

Set under embedder in the config.

`EmbedderConfig`

Field	Type	Default	Description
`provider`	`str`	`'openai'`	Provider of the embedding model (e.g., 'ollama', 'openai')
`config`	`Optional[dict]`	`{}`	Configuration for the specific embedding model

Vector store

Set under vector_store in the config.

`VectorStoreConfig`

Field	Type	Default	Description
`provider`	`str`	`'qdrant'`	Provider of the vector store (e.g., 'qdrant', 'chroma', 'upstash_vector')
`config`	`Optional[Dict]`	`None`	Configuration for the specific vector store

Graph store

Set under graph_store in the config.

`GraphStoreConfig`

Field	Type	Default	Description
`provider`	`str`	`'neo4j'`	Provider of the data store (e.g., 'neo4j', 'memgraph', 'neptune')
`config`	`Union[Neo4jConfig, MemgraphConfig, NeptuneConfig]`	`None`	Configuration for the specific data store
`llm`	`Optional[LlmConfig]`	`None`	LLM configuration for querying the graph store
`custom_prompt`	`Optional[str]`	`None`	Custom prompt to fetch entities from the given text

`Neo4jConfig`

Field	Type	Default	Description
`url`	`Optional[str]`	`None`	Host address for the graph database
`username`	`Optional[str]`	`None`	Username for the graph database
`password`	`Optional[str]`	`None`	Password for the graph database
`database`	`Optional[str]`	`None`	Database for the graph database
`base_label`	`Optional[bool]`	`None`	Whether to use base node label __Entity__ for all entities
`max_connection_pool_size`	`Optional[int]`	`None`	Max parallel sessions per driver (Phase PT1). None = driver default (100).
`connection_acquisition_timeout`	`Optional[float]`	`None`	Seconds a session waits for a free connection before raising (Phase PT1). None = driver default.
`max_connection_lifetime`	`Optional[int]`	`None`	Seconds before a pooled connection is recycled (Phase PT1). None = driver default.

`MemgraphConfig`

Field	Type	Default	Description
`url`	`Optional[str]`	`None`	Host address for the graph database
`username`	`Optional[str]`	`None`	Username for the graph database
`password`	`Optional[str]`	`None`	Password for the graph database

`NeptuneConfig`

Field	Type	Default	Description
`endpoint`	`Optional[str]`	`(Field(None, description='Endpoint to connect to a Neptune Analytics Server as neptune-graph://<graphid>'),)`
`base_label`	`Optional[bool]`	`None`	Whether to use base node label __Entity__ for all entities

Episodic memory (TCMGM)

Set under tcmgm in the config.

`TCMGMConfig`

Episodic memory on top of the graph store: dated events and cause → effect links.

Field	Type	Default	Description
`enabled`	`bool`	`True`	Set up TCMGM when a graph store is configured. Set False to keep the entity graph but skip TCMGM. Has no effect without graph_store.
`build_timeline_on_add`	`bool`	`False`	Also turn the messages of every add(infer=True) into dated events and cause → effect links, as build_timeline does. Costs extra LLM calls and needs the neo4j graph store.
`causal_extraction_mode`	`Literal['llm', 'rules', 'cascade']`	`'llm'`	How cause → effect links are found: 'llm' asks the LLM, 'rules' uses keyword and time-order rules only (no LLM call), 'cascade' tries the rules first and asks the LLM only when they find too little.

Chunking

Set under chunking in the config.

`ChunkingConfig`

Configuration for document chunking.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Enable automatic document chunking
`strategy`	`Literal['character', 'token', 'semantic', 'hierarchical']`	`'token'`	Chunking strategy: - 'character': Split by character count - 'token': Split by token count (recommended) - 'semantic': Split by semantic similarity - 'hierarchical': Split preserving document structure
`chunk_size`	`int`	`512`	Maximum chunk size (tokens or characters depending on strategy)
`chunk_overlap`	`int`	`50`	Overlap between consecutive chunks for context preservation
`separators`	`List[str]`	`['\n\n', '\n', '. ', ' ', '']`	List of separators for recursive splitting (character strategy)
`min_chunk_size`	`int`	`50`	Minimum chunk size (chunks smaller than this are merged)
`max_chunks_per_document`	`Optional[int]`	`None`	Maximum number of chunks per document (None = unlimited)
`tokenizer_model`	`str`	`'gpt-4'`	Model name for token counting (tiktoken)
`semantic_threshold`	`float`	`0.5`	Similarity threshold for semantic chunking
`respect_markdown_headers`	`bool`	`True`	Preserve markdown header boundaries in hierarchical chunking
`merge_chunks_on_retrieval`	`bool`	`True`	Automatically merge chunks from same document during retrieval
`chunk_context_window`	`int`	`1`	Number of neighboring chunks to include for context (±N)
`min_document_size`	`int`	`0`	Minimum document size (in characters) before chunking is applied. Documents smaller than this will be stored as a single memory. Set to 0 to always chunk. Recommended: 1500-2000 for narrative texts.

Privacy (PPMF)

Set under ppmf in the config.

`PPMFConfig`

Privacy-Preserving Memory Firewall configuration.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Enable PPMF
`use_llm_classifier`	`bool`	`True`	Use LLM for sensitivity classification (fallback to rule-based)
`classifier_model`	`Optional[str]`	`None`	Model for classification (uses memory LLM if None)
`classification_threshold`	`float`	`0.7`	Confidence threshold for LLM classification
`encryption_algorithm`	`EncryptionAlgorithm`	`EncryptionAlgorithm.FERNET`	Encryption algorithm to use
`encryption_key_path`	`Optional[str]`	`None`	Path to encryption key file
`key_rotation_enabled`	`bool`	`False`	Enable automatic key rotation
`default_redaction_mode`	`RedactionMode`	`RedactionMode.ENCRYPT`	Default redaction mode
`sensitivity_rules`	`List[SensitivityRule]`	`[]`	Custom sensitivity rules
`redact_telemetry`	`bool`	`True`	Redact sensitive data from telemetry
`enable_adversarial_testing`	`bool`	`False`	Enable MEXTRA-style adversarial testing
`adversarial_test_interval`	`int`	`100`	Run adversarial tests every N memory operations
`async_processing`	`bool`	`True`	Process privacy operations asynchronously
`cache_classifications`	`bool`	`True`	Cache classification results for identical content

Context graph

Set under context_graph in the config.

`ContextGraphConfig`

Master config for the Context-Graph Layer.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Master switch. Off = zero behaviour change.
`backend`	`Literal['networkx', 'neo4j', 'postgres']`	`'networkx'`	networkx (in process), neo4j (the graph_store driver), or postgres (the database in MemoryConfig.state_store; stores the change log there too).
`persist_path`	`Optional[str]`	`None`	Snapshot path for networkx backend (defaults to {outhad_contextkit_dir}/context_graph.pkl when None)
`decay`	`DecayConfig`	`DecayConfig()`
`edges`	`EdgeSynthesisConfig`	`EdgeSynthesisConfig()`
`retrieval`	`RetrievalConfig`	`RetrievalConfig()`
`log_changes`	`bool`	`True`	Write mutation events to the change log (a SQLite file, or the ck_graph_changes table with the postgres backend)

`RetrievalConfig`

Graph-first retrieval parameters.

Field	Type	Default	Description
`enabled`	`bool`	`True`	Use graph-first retrieval when context_graph.enabled is True
`seed_top_k`	`int`	`10`
`expansion_depth`	`int`	`2`
`max_candidates`	`int`	`50`
`edge_weight_floor`	`float`	`0.1`
`alpha_dense`	`float`	`0.55`
`beta_bm25`	`float`	`0.15`
`gamma_graph`	`float`	`0.3`
`algorithm`	`Literal['bfs', 'ppr']`	`'bfs'`	Which retriever to use. 'bfs' (default) preserves pre-Phase-D behaviour; 'ppr' swaps in the PersonalisedPageRankRetriever.
`ppr_damping`	`float`	`0.85`	PageRank damping factor (1-teleport prob).
`ppr_max_iter`	`int`	`200`	Maximum power-iteration steps.
`ppr_tolerance`	`float`	`1e-06`	Convergence tolerance for power iteration.
`delta_personal`	`float`	`0.0`	Weight of the personalised feedback term (δ·personal_boost). 0 = disabled.
`epsilon_frequency`	`float`	`0.0`	Weight of the log-scaled access_count term (ε·frequency). 0 = disabled.
`zeta_success`	`float`	`0.0`	Weight of the (query_hash, memory_id) success-rate term (ζ·success). 0 = disabled.

`EdgeSynthesisConfig`

Controls which structural edges get synthesised on memory add/update.

Field	Type	Default	Description
`enable_reply_to`	`bool`	`True`
`enable_topic_similar`	`bool`	`True`
`enable_document_link`	`bool`	`True`
`enable_temporal_next`	`bool`	`True`
`topic_top_k`	`int`	`5`	Max TOPIC_SIMILAR edges per insert
`topic_min_similarity`	`float`	`0.75`	Cosine similarity floor for topic edges
`reply_to_window_seconds`	`int`	`1800`	Max seconds between memories in the same run to create REPLY_TO
`use_llm_inference`	`bool`	`False`	Opt-in LLM edge synthesis (Phase C). Equivalent to `llm.enabled`.
`llm`	`LLMEdgeConfig`	`LLMEdgeConfig()`

`LLMEdgeConfig`

Phase C — LLM-driven semantic edge synthesis parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Master switch. Mirror of EdgeSynthesisConfig.use_llm_inference (either flag set opts in); kept as its own model so the LLM knobs cluster.
`provider`	`Optional[str]`	`None`	Optional LLM provider override. When None the synthesiser reuses `Memory.llm` (the extraction/update LLM).
`max_pairs_per_insert`	`int`	`3`	Hard cap on LLM classification calls per new memory.
`min_topic_similarity`	`float`	`0.8`	Only LLM-classify pairs whose topic cosine ≥ this floor.
`min_confidence`	`float`	`0.6`	Drop LLM-inferred edges with confidence below this threshold.
`daily_token_budget`	`int`	`100000`	0 disables the budget. Enforced per `user_id` per UTC day.
`tokens_per_call_estimate`	`int`	`500`	Conservative token estimate used for pre-call budget checks.
`timeout_seconds`	`float`	`8.0`	Per-call LLM timeout. Exhausted calls fail-soft to no edges.
`retry_on_schema_violation`	`bool`	`True`	Retry once when the LLM returns malformed JSON.
`cooldown_seconds`	`int`	`900`	After budget exhaustion, cool down for N seconds before retrying.

`DecayConfig`

Edge weight + node relevance decay parameters.

Field	Type	Default	Description
`enabled`	`bool`	`True`
`half_life_days`	`float`	`30.0`	t½ for exponential edge weight decay
`min_edge_weight`	`float`	`0.05`	Edges below this weight are pruned
`min_node_relevance`	`float`	`0.02`	Nodes below this relevance are archived
`tick_on_read`	`bool`	`True`	Lazily apply decay during search traversals

Personalized retrieval (MSPR)

Set under mspr in the config.

`MSPRConfig`

Master config for Multi-Stage Personalized Retrieval.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Master switch. Off = zero behaviour change, zero imports.
`intent`	`IntentConfig`	`IntentConfig()`
`feedback`	`FeedbackConfig`	`FeedbackConfig()`
`frequency`	`FrequencyConfig`	`FrequencyConfig()`
`role`	`RoleConfig`	`RoleConfig()`
`success`	`SuccessConfig`	`SuccessConfig()`

`IntentConfig`

Phase F5 — Query intent classifier parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`
`strategy`	`Literal['regex', 'llm', 'hybrid']`	`'regex'`
`llm_timeout_seconds`	`float`	`2.0`
`cache_size`	`int`	`1024`	LRU cache size for classified queries. 0 disables cache.
`enable_regex_fastpath`	`bool`	`True`	Run regex rules before any LLM call. Hits short-circuit.

`FeedbackConfig`

Phase F3/F4 — record_feedback + δ·personal_boost parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`
`boost_delta`	`float`	`0.15`	Positive relevance delta applied on helpful feedback.
`penalty_delta`	`float`	`0.1`	Absolute value of the negative delta for unhelpful feedback.
`max_boost_per_memory`	`float`	`0.6`	Cap on cumulative boost a single memory can accrue.
`pin_floor_on_boost`	`bool`	`True`	Pin relevance_floor after a helpful boost so decay cannot erase the signal.
`sqlite_path`	`Optional[str]`	`None`	Override path for feedback_events.db. None → default dir.

`FrequencyConfig`

Phase F2 — access_count + ε·frequency parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`
`epsilon_weight`	`float`	`0.05`	Weight applied to the normalised frequency term. Mirrors RetrievalConfig.epsilon_frequency for convenience; the retriever reads from RetrievalConfig, this field is a presentation hint.
`normalise`	`Literal['log1p', 'zscore', 'none']`	`'log1p'`

`RoleConfig`

Phase F6 — role / tenant-aware retrieval parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`
`tenant_field`	`str`	`'tenant_id'`	Key in memory metadata that holds the tenant identifier.
`role_field`	`str`	`'role'`	Key in memory metadata that holds the actor role.
`hard_filter`	`bool`	`True`	When True, deny cross-role/tenant reads pre-rerank. When False, merely deboost via RolePolicy.reweight().

`SuccessConfig`

Phase F7 — historical (query_hash, memory_id) success parameters.

Field	Type	Default	Description
`enabled`	`bool`	`False`
`zeta_weight`	`float`	`0.1`	Mirror of RetrievalConfig.zeta_success for presentation.
`query_hash_algo`	`Literal['sha256', 'minhash']`	`'sha256'`
`sqlite_path`	`Optional[str]`	`None`
`min_sample_size`	`int`	`3`	Only apply the success boost once we have this many samples.

Tenants

Set under tenant in the config.

`TenantConfig`

Master config for tenant + sub-tenant architecture.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Master switch. Off = zero behaviour change, zero imports.
`default_tenant_id`	`str`	`'__default__'`	Tenant id used when the caller does not supply one. Reserved sentinel; cannot be created via the admin API.
`sub_tenant_field`	`str`	`'sub_tenant_id'`	Metadata key holding the sub-tenant identifier on memory payloads.
`isolation`	`IsolationConfig`	`IsolationConfig()`
`registry`	`RegistryConfig`	`RegistryConfig()`

`IsolationConfig`

How strict to be about cross-tenant data leakage.

Field	Type	Default	Description
`mode`	`Literal['filter', 'collection', 'physical']`	`'filter'`	filter — single shared collection; tenant_id added as a metadata filter at query time (matches MSPR F6 today). collection — one vector-store collection per tenant (T3). physical — one DB file / Neo4j DB per tenant. Reserved; not implemented in T3.
`deny_cross_tenant_writes`	`bool`	`True`	When True, raise on writes whose payload tenant_id differs from the resolved tenant.
`require_tenant_id_on_add`	`bool`	`False`	When True and tenant.enabled=True, every Memory.add without a tenant_id raises ValueError.

`RegistryConfig`

SQLite-backed tenant registry parameters.

Field	Type	Default	Description
`sqlite_path`	`Optional[str]`	`None`	Override path for tenant_registry.db. None → {outhad_contextkit_dir}/tenant_registry.db.
`cache_size`	`int`	`512`	LRU cache size for get_tenant() / has_role() lookups. 0 disables caching.

Decay and versioning

Set under decay_v2 in the config.

`DecayV2Config`

Master config for Part D — time-aware decay + versioning.

Field	Type	Default	Description
`enabled`	`bool`	`False`	Master switch. Off = zero behaviour change, zero imports.
`weight_recency`	`float`	`0.6`	Coefficient for the exp-decay recency term in compute_decay_score.
`weight_frequency`	`float`	`0.3`	Coefficient for the log1p-normalised frequency term.
`weight_feedback`	`float`	`0.1`	Coefficient for the tanh-normalised feedback term.
`archive_threshold`	`float`	`0.05`	Memory.archive_low archives every node whose decay_score falls below this floor.
`track_references`	`bool`	`False`	When True, Memory.record_reference(memory_id) bumps access_count + last_accessed_at to reflect downstream usage.
`schedule`	`ScheduleConfig`	`ScheduleConfig()`
`versioning`	`VersioningConfig`	`VersioningConfig()`
`cold_storage`	`ColdStorageConfig`	`ColdStorageConfig()`

`ScheduleConfig`

Periodic decay scheduler parameters (Phase D3).

Field	Type	Default	Description
`enabled`	`bool`	`False`
`interval_seconds`	`float`	`3600.0`	Seconds between scheduler ticks. Default: hourly.
`jitter_seconds`	`float`	`60.0`	Random ± jitter added to each interval to avoid thundering-herd ticks across replicas.
`max_drift_seconds`	`float`	`600.0`	Reserved — bounds clock skew when computing the next tick. Not enforced in D3.

`VersioningConfig`

Immutable versioning parameters (Phase D4/D5).

Field	Type	Default	Description
`mode`	`Literal['overwrite', 'immutable']`	`'overwrite'`	overwrite — pre-feature in-place mutation. immutable — Memory.update creates a new vector-store row and marks the previous row metadata.status='superseded'.
`keep_versions`	`int`	`10`	Pruned chain length per memory. Older versions beyond this depth are dropped on insert / scheduler tick.
`diff_provider`	`Literal['unified', 'json', 'none']`	`'unified'`	Default mode for Memory.diff_versions.

`ColdStorageConfig`

Cold-archival adapter parameters (Phase D7).

Field	Type	Default	Description
`backend`	`Literal['disabled', 'local', 's3', 'postgres']`	`'disabled'`	local disk, S3, or postgres (the database in MemoryConfig.state_store).
`local_root`	`Optional[str]`	`None`	Root directory for the local-disk adapter. None → {outhad_contextkit_dir}/cold_storage.
`s3_bucket`	`Optional[str]`	`None`
`s3_prefix`	`str`	`'outhad_contextkit/'`
`archive_grace_seconds`	`float`	`86400.0`	When the scheduler picks up archived nodes for cold demotion, only nodes archived more than this many seconds ago are moved. Defaults to 24h grace period.