# fa66666/conmemcode architecture

> Architecture diagram of the GitHub repository fa66666/conmemcode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fa66666/conmemcode
- Repository: https://github.com/fa66666/conmemcode

## Overview

ConMem is a pluggable memory layer for single- and multi-agent task hosts. A host retrieves task-relevant cards to condition agent prompts, then submits the completed trajectory for interpretation, admission, graph updates, and later reuse. CAMEL, MacNet, AutoGen, and single-agent integrations are documented; benchmark environments cover code generation, factual QA, and symbolic planning. The README supplies the core stage wiring, while excerpts show interaction hooks, retrieval, storage, and external API calls; some subsystem links therefore reflect documentation rather than sampled implementations.

Main entry points: [`mas_core/memory/backbone/conmem/conmem_module.py`](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/conmem_module.py) (Memory coordinator), [`interactions/multiturn_interaction.py`](https://github.com/fa66666/conmemcode/blob/main/interactions/multiturn_interaction.py) (Multi-turn host), [`utils/agent.py`](https://github.com/fa66666/conmemcode/blob/main/utils/agent.py) (Single agent), [`mas_core/memory/backbone/conmem/llm_backend.py`](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/llm_backend.py) (LLM and embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Agent hosts"]
  node_host_single["Single agent<br/>[agent.py]"]
  node_host_multiturn["Multi-turn host"]
  node_camel["CAMEL host<br/>[camel_main.py]"]
  node_macnet["MacNet host<br/>[macnet_main.py]"]
  node_autogen["AutoGen host<br/>[autogen_main.py]"]
end

subgraph group_memory["ConMem lifecycle"]
  node_conmem["Memory coordinator<br/>[conmem_module.py]"]
  node_interpreter["Trajectory interpreter<br/>[interpreter.py]"]
  node_admission["Card admission<br/>[admission.py]"]
  node_retriever["Card retriever<br/>[retriever.py]"]
  node_coordinator["Graph coordinator<br/>[coordinator.py]"]
  node_serializer["Hint serializer<br/>[serializer.py]"]
end

subgraph group_state["Memory state"]
  node_graph["Memory graph<br/>[memory_graph.py]"]
  node_storage[("Card store<br/>[storage.py]")]
  node_schema["Card schema<br/>[schema.py]"]
end

subgraph group_benchmarks["Task environments"]
  node_kodcode["KodCode tasks<br/>[env.py]"]
  node_triviaqa["TriviaQA tasks<br/>[env.py]"]
  node_popqa["PopQA tasks<br/>[env.py]"]
  node_pddl["PDDL planning<br/>[pddl_env.py]"]
  node_qa_retrieval["QA retrieval<br/>[retrieval_utils.py]"]
  node_popqa_retrieval["PopQA retrieval<br/>[retriever.py]"]
end

subgraph group_integrations["Optional backends"]
  node_llm_backend["LLM and embeddings<br/>[llm_backend.py]"]
  node_simplemem["SimpleMem adapter"]
  node_reme["ReMe adapter"]
end

node_task_user(("Task requester"))
node_llm_service{{"LLM endpoint"}}
node_embedding_service{{"Embedding endpoint"}}
node_search{{"QA search service"}}

node_task_user -->|"submits task"| node_host_single
node_task_user -->|"submits task"| node_host_multiturn
node_task_user -->|"submits task"| node_camel
node_task_user -->|"submits task"| node_macnet
node_task_user -->|"submits task"| node_autogen
node_host_single -->|"retrieves memory"| node_conmem
node_host_single -->|"submits trajectory"| node_conmem
node_host_multiturn -->|"retrieves memory"| node_conmem
node_host_multiturn -->|"submits trajectory"| node_conmem
node_camel -->|"memory hooks"| node_conmem
node_macnet -->|"memory hooks"| node_conmem
node_autogen -->|"memory hooks"| node_conmem
node_conmem -->|"retrieves cards"| node_retriever
node_conmem -->|"interprets trajectory"| node_interpreter
node_conmem -->|"admits candidates"| node_admission
node_conmem -->|"coordinates cards"| node_coordinator
node_conmem -->|"serializes hints"| node_serializer
node_interpreter -->|"requests interpretation"| node_llm_backend
node_admission -.->|"requests scoring"| node_llm_backend
node_retriever -->|"embeds query"| node_llm_backend
node_retriever -->|"reads cards"| node_storage
node_coordinator -->|"walks and merges"| node_graph
node_coordinator -->|"reads and writes"| node_storage
node_admission -->|"writes admitted cards"| node_storage
node_interpreter -->|"creates typed cards"| node_schema
node_serializer -->|"returns prompt hints"| node_host_single
node_serializer -->|"returns prompt hints"| node_host_multiturn
node_llm_backend -->|"calls inference API"| node_llm_service
node_llm_backend -->|"calls embedding API"| node_embedding_service
node_kodcode -->|"provides task"| node_host_multiturn
node_triviaqa -->|"provides task"| node_host_multiturn
node_popqa -->|"provides task"| node_host_multiturn
node_pddl -->|"provides task"| node_host_multiturn
node_triviaqa -->|"issues search queries"| node_qa_retrieval
node_qa_retrieval -->|"posts queries"| node_search
node_popqa -->|"issues search queries"| node_popqa_retrieval
node_popqa_retrieval -->|"posts queries"| node_search
node_host_single -.->|"alternate backend"| node_simplemem
node_host_single -.->|"alternate backend"| node_reme

click node_host_single "https://github.com/fa66666/conmemcode/blob/main/utils/agent.py"
click node_host_multiturn "https://github.com/fa66666/conmemcode/blob/main/interactions/multiturn_interaction.py"
click node_camel "https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/camel/camel_main.py"
click node_macnet "https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/macnet/macnet_main.py"
click node_autogen "https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/autogen/autogen_main.py"
click node_conmem "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/conmem_module.py"
click node_interpreter "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/interpreter.py"
click node_admission "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/admission.py"
click node_retriever "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/retriever.py"
click node_coordinator "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/coordinator.py"
click node_serializer "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/serializer.py"
click node_graph "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/memory_graph.py"
click node_storage "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/storage.py"
click node_schema "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/schema.py"
click node_kodcode "https://github.com/fa66666/conmemcode/blob/main/data/kodcode/env.py"
click node_triviaqa "https://github.com/fa66666/conmemcode/blob/main/data/triviaqa/env.py"
click node_popqa "https://github.com/fa66666/conmemcode/blob/main/data/popqa/env.py"
click node_pddl "https://github.com/fa66666/conmemcode/blob/main/data/pddl/env/pddl_env.py"
click node_llm_backend "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/llm_backend.py"
click node_qa_retrieval "https://github.com/fa66666/conmemcode/blob/main/common/utils/retrieval_utils.py"
click node_popqa_retrieval "https://github.com/fa66666/conmemcode/blob/main/data/popqa/retriever.py"
click node_simplemem "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/simplemem/centralized_adapter.py"
click node_reme "https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/reme/centralized_adapter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_single,node_host_multiturn,node_camel,node_macnet,node_autogen toneBlue
class node_conmem,node_interpreter,node_admission,node_retriever,node_coordinator,node_serializer toneAmber
class node_graph,node_storage,node_schema toneMint
class node_kodcode,node_triviaqa,node_popqa,node_pddl,node_qa_retrieval,node_popqa_retrieval,node_task_user toneRose
class node_llm_backend,node_simplemem,node_reme,node_llm_service,node_embedding_service,node_search toneIndigo
```

## Components

### Agent hosts

- [Single agent](https://github.com/fa66666/conmemcode/blob/main/utils/agent.py): `utils/agent.py`
- [Multi-turn host](https://github.com/fa66666/conmemcode/blob/main/interactions/multiturn_interaction.py): `interactions/multiturn_interaction.py`
- [CAMEL host](https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/camel/camel_main.py): `mas_core/structures/camel/camel_main.py`
- [MacNet host](https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/macnet/macnet_main.py): `mas_core/structures/macnet/macnet_main.py`
- [AutoGen host](https://github.com/fa66666/conmemcode/blob/main/mas_core/structures/autogen/autogen_main.py): `mas_core/structures/autogen/autogen_main.py`

### ConMem lifecycle

- [Memory coordinator](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/conmem_module.py): `mas_core/memory/backbone/conmem/conmem_module.py`
- [Trajectory interpreter](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/interpreter.py): `mas_core/memory/backbone/conmem/interpreter.py`
- [Card admission](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/admission.py): `mas_core/memory/backbone/conmem/admission.py`
- [Card retriever](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/retriever.py): `mas_core/memory/backbone/conmem/retriever.py`
- [Graph coordinator](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/coordinator.py): `mas_core/memory/backbone/conmem/coordinator.py`
- [Hint serializer](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/serializer.py): `mas_core/memory/backbone/conmem/serializer.py`

### Memory state

- [Memory graph](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/memory_graph.py): `mas_core/memory/backbone/conmem/memory_graph.py`
- [Card store](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/storage.py): `mas_core/memory/backbone/conmem/storage.py`
- [Card schema](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/schema.py): `mas_core/memory/backbone/conmem/schema.py`

### Task environments

- [KodCode tasks](https://github.com/fa66666/conmemcode/blob/main/data/kodcode/env.py): `data/kodcode/env.py`
- [TriviaQA tasks](https://github.com/fa66666/conmemcode/blob/main/data/triviaqa/env.py): `data/triviaqa/env.py`
- [PopQA tasks](https://github.com/fa66666/conmemcode/blob/main/data/popqa/env.py): `data/popqa/env.py`
- [PDDL planning](https://github.com/fa66666/conmemcode/blob/main/data/pddl/env/pddl_env.py): `data/pddl/env/pddl_env.py`
- [QA retrieval](https://github.com/fa66666/conmemcode/blob/main/common/utils/retrieval_utils.py): `common/utils/retrieval_utils.py`
- [PopQA retrieval](https://github.com/fa66666/conmemcode/blob/main/data/popqa/retriever.py): `data/popqa/retriever.py`

### Optional backends

- [LLM and embeddings](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/conmem/llm_backend.py): `mas_core/memory/backbone/conmem/llm_backend.py`
- [SimpleMem adapter](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/simplemem/centralized_adapter.py): `mas_core/memory/backbone/simplemem/centralized_adapter.py`
- [ReMe adapter](https://github.com/fa66666/conmemcode/blob/main/mas_core/memory/backbone/reme/centralized_adapter.py): `mas_core/memory/backbone/reme/centralized_adapter.py`

### Other components

- **Task requester**
- **LLM endpoint**
- **Embedding endpoint**
- **QA search service**

## Connections

- Task requester → Single agent: submits task
- Task requester → Multi-turn host: submits task
- Task requester → CAMEL host: submits task
- Task requester → MacNet host: submits task
- Task requester → AutoGen host: submits task
- Single agent → Memory coordinator: retrieves memory
- Single agent → Memory coordinator: submits trajectory
- Multi-turn host → Memory coordinator: retrieves memory
- Multi-turn host → Memory coordinator: submits trajectory
- CAMEL host → Memory coordinator: memory hooks
- MacNet host → Memory coordinator: memory hooks
- AutoGen host → Memory coordinator: memory hooks
- Memory coordinator → Card retriever: retrieves cards
- Memory coordinator → Trajectory interpreter: interprets trajectory
- Memory coordinator → Card admission: admits candidates
- Memory coordinator → Graph coordinator: coordinates cards
- Memory coordinator → Hint serializer: serializes hints
- Trajectory interpreter → LLM and embeddings: requests interpretation
- Card admission → LLM and embeddings: requests scoring
- Card retriever → LLM and embeddings: embeds query
- Card retriever → Card store: reads cards
- Graph coordinator → Memory graph: walks and merges
- Graph coordinator → Card store: reads and writes
- Card admission → Card store: writes admitted cards
- Trajectory interpreter → Card schema: creates typed cards
- Hint serializer → Single agent: returns prompt hints
- Hint serializer → Multi-turn host: returns prompt hints
- LLM and embeddings → LLM endpoint: calls inference API
- LLM and embeddings → Embedding endpoint: calls embedding API
- KodCode tasks → Multi-turn host: provides task
- TriviaQA tasks → Multi-turn host: provides task
- PopQA tasks → Multi-turn host: provides task
- PDDL planning → Multi-turn host: provides task
- TriviaQA tasks → QA retrieval: issues search queries
- QA retrieval → QA search service: posts queries
- PopQA tasks → PopQA retrieval: issues search queries
- PopQA retrieval → QA search service: posts queries
- Single agent → SimpleMem adapter: alternate backend
- Single agent → ReMe adapter: alternate backend
