# memcore-agent/memcore architecture

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

- Interactive diagram: https://gitdiagram.com/memcore-agent/memcore
- Repository: https://github.com/memcore-agent/memcore

## Overview

#### Purpose and Entry Points
ailive_MemCore is a Python library for adding persistent, entity-oriented memory to an LLM agent. It combines a chat/ReAct agent, knowledge-graph retrieval, automatic memory updates, and persona/chat-history context.
- Library API: `src/ailive/agent/chat_agent.py`
- Memory package: `src/ailive/MemCore/__init__.py`
- Demo application entry point: `MemCore_app/MemCore_app.py`

#### Chat-Agent Orchestration
`ChatAgent` is the primary integration boundary for consumers. It accepts paths for system persona, user persona, chat history, MemCore stream, and entity knowledge store; it also exposes custom-tool registration/removal. The agent coordinates query handling, tool execution, retrieval, response generation, and persistence.
- `src/ailive/agent/chat_agent.py`
- `src/ailive/agent/base_agent.py`
- `src/ailive/agent/data_types.py`

#### Memory Model: Stream to Knowledge Store
The memory subsystem has two persistence representations. The MemCore stream records entity occurrences with timestamps (interaction breadth). The entity knowledge store aggregates stream entries into per-entity count and most-recent-reference metadata (depth/relevance). These are designed to feed subsequent response context and preference inference.
- `src/ailive/MemCore/memcore_stream.py`
- `src/ailive/MemCore/entity_knowledge_store.py`
- `src/ailive/MemCore/types.py`

#### Context Construction and Conversation State
Agent context is assembled from personas, retained/summarized chat history, relevant graph entities, and memory-derived entity rankings. File-backed JSON/text data enables the demo’s stateful operation; this is a persistence boundary rather than a transactional database interface.
- `MemCore_app/data/MemCore_stream.json`
- `MemCore_app/data/entity_knowledge_store.json`
- `MemCore_app/data/past_chat.json`

#### Knowledge Retrieval and Writeback
The intended retrieval design uses LlamaIndex-style graph querying: identify query entities, retrieve a bounded related subgraph, then use it as answer context. Agent responses are written back so future queries can retrieve newly learned entities. Development artifacts include serialized graph/vector/doc stores, suggesting local/offline index experimentation alongside the Neo4j-backed design described by the project.
- `dev/recursive_retrieval/langchain_retrieval/retrieve.py`
- `dev/recursive_retrieval/entity_extraction/entity_extraction.py`
- `dev/KG_mecore_stream/storage_graph/ch1_2_3_4/docstore.json`

#### Tools and Model Boundary
The agent supports a configurable default tool set (search, vision, location, stocks) plus arbitrary Python callables. LLM/tool adapters are separated from agent orchestration. Supported model runtimes are local Ollama models by default, with OpenAI model alternatives; external search and domain tools may require hosted API credentials.
- `src/ailive/agent/llm_api/tools.py`
- `src/ailive/agent/llm_api`
- `src/ailive/synonym_expand/synonym.py`

#### Infrastructure and External Services
Core infrastructure is Python (README limits runtime to Python ≤3.11.9), package dependencies from `requirements.txt`, and optional local Ollama. The documented production graph backend is Neo4j. Optional integrations require OpenAI, Perplexity, Google Maps, and Alpha Vantage credentials. The repository’s README references older `streamlit_app` paths; the checked-in UI is instead under `MemCore_app/`.
- `requirements.txt`
- `MemCore.toml`
- `MemCore_app/MemCore_app.py`

Main entry points: [`src/ailive/agent/chat_agent.py`](https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/chat_agent.py) (ChatAgent), [`src/ailive/MemCore/__init__.py`](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/__init__.py) (MemCore package), [`src/ailive/MemCore/memcore_stream.py`](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/memcore_stream.py) (MemCore stream), [`src/ailive/MemCore/entity_knowledge_store.py`](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/entity_knowledge_store.py) (Entity knowledge store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_chat_agent["ChatAgent<br/>integration API<br/>[chat_agent.py]"]
  node_agent_base_types["Agent base and types<br/>agent contracts<br/>[base_agent.py]"]
  node_context["Context assembly<br/>conversation context<br/>[chat_agent.py]"]
  node_tools["Tool adapters<br/>LLM tools<br/>[tools.py]"]
end

subgraph group_memory["Persistent memory"]
  node_memcore_api["MemCore package<br/>memory API<br/>[__init__.py]"]
  node_memory_stream["MemCore stream<br/>occurrence log<br/>[memcore_stream.py]"]
  node_entity_store[("Entity knowledge store<br/>entity metadata")]
  node_memory_types["Memory types<br/>data contracts<br/>[types.py]"]
  node_state_files["Demo state files<br/>JSON persistence"]
end

subgraph group_retrieval["Knowledge retrieval"]
  node_entity_extraction["Entity extraction<br/>indexing stage"]
  node_graph_retrieval["Graph retrieval<br/>subgraph query<br/>[retrieve.py]"]
  node_local_index[("Local graph/vector artifacts<br/>offline index storage<br/>[docstore.json]")]
end

subgraph group_integrations["Models and services"]
  node_llm_runtime{{"LLM runtime adapters<br/>model integration"}}
  node_external_services{{"External services<br/>optional providers"}}
end

node_demo["Demo application<br/>Python UI<br/>[MemCore_app.py]"]

node_demo -->|"uses"| node_chat_agent
node_chat_agent -->|"implements"| node_agent_base_types
node_chat_agent -->|"assembles"| node_context
node_chat_agent -->|"invokes"| node_tools
node_chat_agent -->|"generates with"| node_llm_runtime
node_chat_agent -->|"reads and updates"| node_memcore_api
node_context -->|"loads history"| node_state_files
node_context -->|"uses rankings"| node_entity_store
node_memory_stream -->|"aggregates into"| node_entity_store
node_memcore_api -->|"records"| node_memory_stream
node_memcore_api -->|"maintains"| node_entity_store
node_memcore_api -->|"uses"| node_memory_types
node_memory_stream -->|"persists"| node_state_files
node_entity_store -->|"persists"| node_state_files
node_chat_agent -.->|"retrieves context"| node_graph_retrieval
node_graph_retrieval -.->|"queries graph backend"| node_external_services
node_graph_retrieval -.->|"experiments with"| node_local_index
node_chat_agent -.->|"writes responses back"| node_entity_extraction
node_entity_extraction -.->|"records entities"| node_memory_stream
node_entity_extraction -.->|"updates graph"| node_external_services
node_tools -.->|"calls optional APIs"| node_external_services

click node_demo "https://github.com/memcore-agent/memcore/blob/main/MemCore_app/MemCore_app.py"
click node_chat_agent "https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/chat_agent.py"
click node_agent_base_types "https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/base_agent.py"
click node_context "https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/chat_agent.py"
click node_tools "https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/llm_api/tools.py"
click node_llm_runtime "https://github.com/memcore-agent/memcore/tree/main/src/ailive/agent/llm_api"
click node_memcore_api "https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/__init__.py"
click node_memory_stream "https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/memcore_stream.py"
click node_entity_store "https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/entity_knowledge_store.py"
click node_memory_types "https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/types.py"
click node_state_files "https://github.com/memcore-agent/memcore/blob/main/MemCore_app/data/MemCore_stream.json"
click node_entity_extraction "https://github.com/memcore-agent/memcore/blob/main/dev/recursive_retrieval/entity_extraction/entity_extraction.py"
click node_graph_retrieval "https://github.com/memcore-agent/memcore/blob/main/dev/recursive_retrieval/langchain_retrieval/retrieve.py"
click node_local_index "https://github.com/memcore-agent/memcore/blob/main/dev/KG_mecore_stream/storage_graph/ch1_2_3_4/docstore.json"

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_chat_agent,node_agent_base_types,node_context,node_tools toneBlue
class node_memcore_api,node_memory_stream,node_entity_store,node_memory_types,node_state_files toneAmber
class node_entity_extraction,node_graph_retrieval,node_local_index toneMint
class node_llm_runtime,node_external_services toneRose
class node_demo toneNeutral
```

## Components

### Agent runtime

- [ChatAgent](https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/chat_agent.py): integration API · Consumer-facing orchestration boundary. · `src/ailive/agent/chat_agent.py`
- [Agent base and types](https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/base_agent.py): agent contracts · `src/ailive/agent/base_agent.py`
- [Context assembly](https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/chat_agent.py): conversation context · Combines personas, history, graph results, and memory rankings. · `src/ailive/agent/chat_agent.py`
- [Tool adapters](https://github.com/memcore-agent/memcore/blob/main/src/ailive/agent/llm_api/tools.py): LLM tools · Default tools and custom Python callable support. · `src/ailive/agent/llm_api/tools.py`

### Persistent memory

- [MemCore package](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/__init__.py): memory API · `src/ailive/MemCore/__init__.py`
- [MemCore stream](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/memcore_stream.py): occurrence log · Timestamped entity occurrences. · `src/ailive/MemCore/memcore_stream.py`
- [Entity knowledge store](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/entity_knowledge_store.py): entity metadata · Per-entity count and most-recent reference. · `src/ailive/MemCore/entity_knowledge_store.py`
- [Memory types](https://github.com/memcore-agent/memcore/blob/main/src/ailive/MemCore/types.py): data contracts · `src/ailive/MemCore/types.py`
- [Demo state files](https://github.com/memcore-agent/memcore/blob/main/MemCore_app/data/MemCore_stream.json): JSON persistence · Stream, entity store, and prior chat are file-backed. · `MemCore_app/data/MemCore_stream.json`

### Knowledge retrieval

- [Entity extraction](https://github.com/memcore-agent/memcore/blob/main/dev/recursive_retrieval/entity_extraction/entity_extraction.py): indexing stage · Extracts learned entities for graph writeback. · `dev/recursive_retrieval/entity_extraction/entity_extraction.py`
- [Graph retrieval](https://github.com/memcore-agent/memcore/blob/main/dev/recursive_retrieval/langchain_retrieval/retrieve.py): subgraph query · Identifies query entities and retrieves bounded related context. · `dev/recursive_retrieval/langchain_retrieval/retrieve.py`
- [Local graph/vector artifacts](https://github.com/memcore-agent/memcore/blob/main/dev/KG_mecore_stream/storage_graph/ch1_2_3_4/docstore.json): offline index storage · Serialized doc, graph, and vector-store experiments. · `dev/KG_mecore_stream/storage_graph/ch1_2_3_4/docstore.json`

### Models and services

- [LLM runtime adapters](https://github.com/memcore-agent/memcore/tree/main/src/ailive/agent/llm_api): model integration · Local Ollama default with OpenAI alternatives. · `src/ailive/agent/llm_api`
- **External services**: optional providers · Neo4j graph backend plus search and domain APIs.

### Other components

- [Demo application](https://github.com/memcore-agent/memcore/blob/main/MemCore_app/MemCore_app.py): Python UI · Stateful demonstration entry point. · `MemCore_app/MemCore_app.py`

## Connections

- Demo application → ChatAgent: uses
- ChatAgent → Agent base and types: implements
- ChatAgent → Context assembly: assembles
- ChatAgent → Tool adapters: invokes
- ChatAgent → LLM runtime adapters: generates with
- ChatAgent → MemCore package: reads and updates
- Context assembly → Demo state files: loads history
- Context assembly → Entity knowledge store: uses rankings
- MemCore stream → Entity knowledge store: aggregates into
- MemCore package → MemCore stream: records
- MemCore package → Entity knowledge store: maintains
- MemCore package → Memory types: uses
- MemCore stream → Demo state files: persists
- Entity knowledge store → Demo state files: persists
- ChatAgent → Graph retrieval: retrieves context
- Graph retrieval → External services: queries graph backend
- Graph retrieval → Local graph/vector artifacts: experiments with
- ChatAgent → Entity extraction: writes responses back
- Entity extraction → MemCore stream: records entities
- Entity extraction → External services: updates graph
- Tool adapters → External services: calls optional APIs