Memory Modules#

This page documents the stable public memory facade.

Stable public memory facade exports.

class design_research_agents.memory.ChromaMemoryStore(*, persist_directory=None, collection_name='design_research_agents_memory', embedding_provider=None, embedding_model=None, client=None)[source]

Persistent Chroma-backed memory store with optional vector retrieval.

Initialize a Chroma-backed memory store.

Parameters:

persist_directory – Optional Chroma persistence directory.
collection_name – Collection name shared across namespaces.
embedding_provider – Optional embedding provider for vector retrieval.
embedding_model – Optional model key used for embedding rows.
client – Optional injected Chroma client for testing.

Raises:

ImportError – If chromadb is unavailable.

close()[source]: Release any store-owned resources.

property persist_directory: Return persistence directory used by this store.

search(query)[source]: Search records using lexical relevance and optional vector similarity.

write(records, *, namespace='default')[source]: Persist records and return normalized stored records.

class design_research_agents.memory.EmbeddingProvider(*args, **kwargs)[source]

Protocol for converting text payloads into dense vectors.

embed(texts)[source]

Embed one or more texts.

Parameters:: texts – Input texts to embed.
Returns:: Embedding vectors in input order, or None when embeddings are unavailable and lexical fallback should be used.

property model_name

Return stable embedding model identifier.

Returns:: Stable embedding model identifier.

class design_research_agents.memory.GraphEdgeRecord(*, source_id, target_id, relationship, edge_id=None, metadata=<factory>, created_at=None, updated_at=None)[source]

One graph edge stored in a graph-memory backend.

created_at: ISO timestamp for edge creation.

edge_id: Stable edge identifier; derived by stores when omitted.

metadata: Optional edge metadata fields.

relationship: Normalized relationship label.

source_id: Source node identifier.

target_id: Target node identifier.

to_dict()[source]

Return a JSON-serializable dictionary representation.

Returns:: Serialized dataclass payload.

updated_at: ISO timestamp for last edge update.

class design_research_agents.memory.GraphMemoryStore(*args, **kwargs)[source]

Protocol implemented by graph-memory stores used by agents and patterns.

close()[source]: Release any store-owned resources.

query_subgraph(query)[source]

Retrieve a relevant graph subgraph for one structured query.

Parameters:: query – Structured graph-memory search query.
Returns:: Retrieved subgraph result.

upsert_edges(edges, *, namespace='default')[source]

Persist graph edges and return normalized stored entries.

Parameters:

edges – Edge payloads to persist.
namespace – Namespace partition to store edges under.

Returns:

Stored edges including ids and timestamps.

upsert_nodes(nodes, *, namespace='default')[source]

Persist graph nodes and return normalized stored entries.

Parameters:

nodes – Node payloads to persist.
namespace – Namespace partition to store nodes under.

Returns:

Stored nodes including timestamps.

class design_research_agents.memory.GraphNodeRecord(*, node_id, name, node_type='entity', description='', metadata=<factory>, created_at=None, updated_at=None, score=None)[source]

One graph node stored in a graph-memory backend.

created_at: ISO timestamp for node creation.

description: Optional free-text node description.

metadata: Optional node metadata fields.

name: Human-readable node label.

node_id: Stable node identifier.

node_type: Coarse node type such as component or formula.

score: Optional retrieval score when returned by a graph query.

to_dict()[source]

Return a JSON-serializable dictionary representation.

Returns:: Serialized dataclass payload.

updated_at: ISO timestamp for last node update.

class design_research_agents.memory.GraphSearchQuery(*, text, namespace='default', top_k=3, max_hops=1, min_score=None, metadata_filters=<factory>, node_type_filters=(), relationship_filters=())[source]

Structured graph-memory search query.

max_hops: Maximum graph-traversal distance from matched seed nodes.

metadata_filters: Exact-match metadata filters applied to candidate nodes.

min_score: Optional minimum score threshold for matched seed nodes.

namespace: Namespace partition used for isolation.

node_type_filters: Optional allowed node types.

relationship_filters: Optional allowed relationship labels for returned edges.

text: Natural language query text.

to_dict()[source]

Return a JSON-serializable dictionary representation.

Returns:: Serialized dataclass payload.

top_k: Maximum number of seed nodes to retrieve before expansion.

class design_research_agents.memory.GraphSubgraphResult(*, namespace, query_text, matched_node_ids=(), nodes=(), edges=())[source]

One retrieved graph subgraph.

edges: Retrieved edges connecting included nodes.

matched_node_ids: Seed node ids that matched the text query before graph expansion.

namespace: Namespace partition queried.

nodes: Retrieved nodes, including traversal context.

query_text: Original query text.

to_dict()[source]

Return a JSON-serializable dictionary representation.

Returns:: Serialized dataclass payload.

class design_research_agents.memory.KnowledgeDocument(*, document_id, title, content, sources=())[source]

One canonical knowledge document ready for ingestion.

content: Markdown document content to chunk and ingest.

document_id: Stable document identifier within one profile.

sources: Structured provenance sources associated with the document.

title: Human-readable document title.

to_dict()[source]: Return a JSON-serializable dictionary representation.

class design_research_agents.memory.KnowledgeProfile(*, name, description, records, graph_nodes=(), graph_edges=(), sources=())[source]

Materialized deterministic knowledge profile.

description: Human-readable profile summary.

graph_edges: Graph edges included in the profile.

graph_nodes: Graph nodes included in the profile.

name: Stable profile name.

records: Vector/text memory records included in the profile.

sources: Structured provenance sources for the profile.

to_dict()[source]: Return a JSON-serializable dictionary representation.

class design_research_agents.memory.KnowledgeProfileSeedResult(*, profile_name, namespace, memory_records_written, graph_nodes_written, graph_edges_written)[source]

Summary of seeding one built-in knowledge profile into configured stores.

graph_edges_written: Number of graph edges written.

graph_nodes_written: Number of graph nodes written.

memory_records_written: Number of vector/text memory records written.

namespace: Namespace the profile was written into.

profile_name: Seeded profile name.

to_dict()[source]: Return a JSON-serializable dictionary representation.

class design_research_agents.memory.KnowledgeSource(*, label='', uri='', kind='unspecified')[source]

One structured provenance source for ingested knowledge.

kind: Coarse provenance kind such as background_reference.

label: Human-readable source label.

to_dict()[source]: Return a JSON-serializable dictionary representation.

uri: Canonical source URI.

class design_research_agents.memory.LLMEmbeddingProvider(*, llm_client, model=None, enable_lexical_fallback=True)[source]

Embedding adapter that delegates to an LLM client/backend when available.

Initialize one embedding adapter from an existing LLM client.

Parameters:

llm_client – LLM client instance that may expose embeddings.
model – Optional explicit embedding model identifier.
enable_lexical_fallback – Return None instead of raising when embeddings are unsupported.

embed(texts)[source]

Embed texts through available client/backend embedding APIs.

Parameters:: texts – Input texts to embed.
Returns:: List of vectors, or None when lexical fallback is enabled and embeddings are unavailable.
Raises:: Exception – Raised when embeddings fail and lexical fallback is disabled.

property model_name

Return configured embedding model identifier.

Returns:: Resolved embedding model identifier.

class design_research_agents.memory.NetworkXGraphMemoryStore(*, networkx_module=None)[source]

Lightweight graph-memory backend built on top of NetworkX.

Initialize the graph store.

Parameters:: networkx_module – Optional injected networkx module used for testing or custom graph implementations.
Raises:: ImportError – If networkx is unavailable.

close()[source]: Release any store-owned resources.

query_subgraph(query)[source]: Retrieve one relevant graph subgraph for a structured query.

upsert_edges(edges, *, namespace='default')[source]: Persist graph edges and return normalized stored edges.

upsert_nodes(nodes, *, namespace='default')[source]: Persist graph nodes and return normalized stored nodes.

class design_research_agents.memory.SQLiteMemoryStore(*, db_path=None, embedding_provider=None, embedding_model=None)[source]

Persistent local memory store with optional embedding-based retrieval.

Initialize a local sqlite memory store.

Parameters:

db_path – Optional sqlite database file path.
embedding_provider – Optional embedding provider for vector retrieval.
embedding_model – Optional model key used for embedding rows.

close()[source]: Close sqlite connection.

property db_path

Return sqlite database path used by this store.

Returns:: Configured sqlite database path.

search(query)[source]

Search records using lexical relevance and optional vector similarity.

Parameters:: query – Structured memory search query.
Returns:: Ranked memory records matching the query.

write(records, *, namespace='default')[source]

Persist records and return normalized stored records.

Parameters:

records – Memory record payloads to persist.
namespace – Namespace partition for writes.

Returns:

Stored records in caller-provided order.

design_research_agents.memory.extract_graph_records_from_text(text)[source]

Extract nodes and relationships from simple design statements.

The extraction is intentionally heuristic and deterministic. It is useful for bootstrapping graph memory from structured requirement text, but it is not intended to replace model-based information extraction.

Parameters:: text – Source text containing simple relationship statements.
Returns:: Tuple (nodes, edges) extracted from the text.

design_research_agents.memory.ingest_knowledge_documents(profile_name, *, description, documents, sources=())[source]

Ingest canonical knowledge documents into one materialized profile.

Parameters:

profile_name – Stable profile name.
description – Human-readable profile summary.
documents – Canonical documents to ingest.
sources – Optional structured provenance entries for the profile.

Returns:

Materialized knowledge profile with text records and heuristic graph data.

Raises:

ValueError – If required values are missing or invalid.

design_research_agents.memory.iter_builtin_knowledge_profiles()[source]: Return built-in knowledge profiles in deterministic name order.

design_research_agents.memory.list_builtin_knowledge_profiles()[source]: Return available built-in knowledge profile names.

design_research_agents.memory.load_builtin_knowledge_profile(profile_name)[source]

Return one built-in knowledge profile by name.

Parameters:: profile_name – Built-in profile name.
Returns:: Built-in knowledge profile.
Raises:: ValueError – If the requested profile is unknown.

design_research_agents.memory.seed_builtin_knowledge_profile(profile_name, *, memory_store=None, graph_store=None, namespace='default')[source]

Seed one built-in profile into configured memory stores.

Parameters:

profile_name – Built-in profile name.
memory_store – Optional text/vector memory store.
graph_store – Optional graph memory store.
namespace – Namespace used for writes.

Returns:

Summary of records written.

Raises:

ValueError – If both memory_store and graph_store are missing.