memcore-agent/memcore

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