{"slug": "charactermemory-memory-system-for-ai-characters", "title": "CharacterMemory: Memory System for AI Characters", "summary": "CharacterMemory, a memory system for AI characters from developer FrancescoCaracciolo, is distributed as a pip package and MCP server that recalls memories by emotional impact, location, recency and recall frequency rather than perfect recall. The library installs via `pip install charactermemory`, or `pip install 'charactermemory[server]'` for the FastAPI server, WebUI and MCP endpoint, and talks to any OpenAI-compatible /v1 endpoint for chat and embeddings. It ships eight toggleable memory systems including Fact Memory, Episodes Memory, Emotions and User directives, and serves /context, /save, /gui and /mcp on port 8000.", "body_md": "**AI Characters that live, remember and forget**\n\n[**Quick Start**](#quick-start) •\n  [**Installation**](#installation) •\n  [**General Idea**](#general-idea) •\n  [**Knowledge Graph**](#knowledge-graph-retrieval) •\n  [**Demo Projects**](#demo-and-projects-using-it) •\n  **Introduction Video**[** Introduction Video**](https://youtu.be/rdJ7QPhogNY#gh-light-mode-only) •\n  [**Credits**](#credits-and-ai-disclosure) •\n  **Documentation ↗**\n\nUnlike other memory systems, Character Memory is not created for perfect recall, but to **recall like a human**, **make bonds with users** and **keep track of the character's lifetime**.\n\nLike humans, in CharacterMemory, memories are recalled based on **how emotionally impactful** an episode was, in which **location** the character is, how **recent** is the memory and how **often** he recalls it.\n\n| Memory Explorer | World Editor | Knowledge Graph | Live Recall | \n|---|---|---|---|\n|      |      |      |      | \n\n**Character Memory is both a library for developers and a ready-to-integrate tool for third party applications**\nIt provides a:\n\n- pip package, used by developers to integrate the library\n- MCP server, to integrate tools to read and edit memory into Agents\n- API to query and save memory\n- A Web Interface to create characters, view memories and chat with them\n\n```\npip install charactermemory              # the library\npip install 'charactermemory[server]'    # + FastAPI server, WebUI and MCP endpoint\n```\n\nThe library talks to any OpenAI-compatible `/v1` endpoint for both the chat model and the embeddings server:\n\n```\nexport OPENAI_BASE_URL=\"http://127.0.0.1:9999/v1\"\nexport OPENAI_API_KEY=\"anything\"\nexport OPENAI_MODEL=\"my-chat-model\"\nexport OPENAI_EMBEDDINGS_BASE_URL=\"http://127.0.0.1:9999/v1\"\nexport OPENAI_EMBEDDINGS_MODEL=\"my-embeddings-model\"\n```\n\nA character is just a directory: `Information/` lore files, `Dialogues/` examples, and an optional `config.yaml` with persona, prompts and memory toggles.\n\n``` python\nfrom character_memory import CharacterAgent, LLMConfig, EmbeddingConfig, MemoryConfig\n\nagent = CharacterAgent(directory=\"assets/Kurisu\", name=\"Kurisu\")\nagent.load_from_config(LLMConfig(), EmbeddingConfig(), MemoryConfig())\nagent.build()   # load or build the memory indexes (idempotent)\n\nchat = agent.create_chat(user=\"michael\", title=\"phonewave intro\")\nchat.add_message(\"user\", \"Hi, I'm Michael, a nuclear engineer called in by Daru.\")\n\nfor chunk in agent.generate_answer(chat, stream=True):   # persisted + auto-extracted\n    print(chunk, end=\"\", flush=True)\ncharactermemory-server    # serves /context, /save, /gui and /mcp on :8000\n```\n\nOpen [http://localhost:8000/gui](http://localhost:8000/gui) to create characters, browse and edit their memories and explore the knowledge graph, or point an MCP client (Claude Desktop, Cursor, …) at `http://localhost:8000/mcp?character=Kurisu`.\n\nThe full walkthrough of all four usage modes (full library, context-only, MCP server, HTTP API + WebUI) is in [docs/getting_started.md](https://github.com/FrancescoCaracciolo/CharacterMemory/blob/master/docs/getting_started.md).\n\nCharacter Memory provides the following built-in memory systems (which can be enabled/disabled):\n\n1. Character Info: documents about the base character's lore, preferences and general information. Allows for lore consistency.\n2. Dialogue Examples: documents about examples of conversations between the character and other characters, used to copy it conversation style\n3. **Fact Memory** : save facts like \"User is an engineer\"\n4. **Episodes Memory** : save episodes like \"I talked with the user about quantum physics\"\n5. User directives: instructions given by the user that recall when needed, for example \"When I ask you to do X, do Y\". Mainly used for agent/assistant-like characters.\n6. Conversation Events: just saves conversations with the user. Recall on this memory is only done when necessary\n7. **Emotions** : keep track of current character's base emotions and emotions towards a user specifically\n8. **World** : keep track of the character's location, routines, sleep, hunger and energy\n9. **Calendar** : keep track of events\n10. User Summary: a rolling summary of the user\n\n- **Recall** is usually done via Embeddings (Similarity) + BM25 (Lexical) search on all the memories, but also considering emotions, recency and other parameters. Some memories are made to stay regardless.\n- Every 5 or 10 turns (user-defined), an **LLM extraction process begins** , which, considering already existing context, adds entries for all of the memories that need it.\n- New extracted memories are compared to old memories, and a **deduplication process** begins if too similar memories or conflicting memories are detected.\n\nKnowledge Graph Retrieval provides an aggregation of retrieval-based memories and connects them in order to provide a more advanced retrieval. There are multiple node types:\n\n- **Self node** : maps the character itself, central and main node of the graph.\n- **Person node** : maps person and their relationship with them, activates when a person is metioned or the character is talking to that person\n- **Episode node** : maps episodes\n- **Fact node** : maps facts\n- **Location node** : maps locations, activates automatically when the character is in that location, or the location is mentioned\n- **Entity Node** : maps entities, special objects or things in the conversation\n\nDepending on the nodes they connect, edges can map the **emotions** about an event, **relationship** with other poeple, **two events that get recalled together**, the importance and how recent an event is.\n\nAt the end,\n\n- People with strong bonds are more likely to be recalled\n- Episodes that cause strong emotions, or that caused similar emotions to current are more likely to be recalled\n- Episodes that are related to a common entity are more likely to be recalled\n- Episodes that happened in the same location the character currently is, are more likely to be recalled\n\nThe knowledge graph requires one additional LLM call after every extraction. (And tens of LLM calls to ingest existing memories)\n\n- **Amadeus System** (by me)\nShow the knowledge graph to the user while generating the answer and allow the user to explore it.\n\nStill in beta, not available to the public yet.\n\n## AmadeusTest.mp4\n\n- [**Amadeus Project**](https://github.com/reflectors02/Amadeus-Project/tree/main) : experimenting with the new memory system\n- [**Nyarch Assistant**](https://github.com/NyarchLinux/NyarchAssistant) : will have native support to CharacterMemory starting from v1.6.0\n\n- The logo, banner and graphics are designed by [GiuliettesPhotography](https://www.instagram.com/giuliettesphotography)\n- The code architecture, memory classes, API desgin and core code is totally **human written** and coded, with the sole exception of some patches that were heavily human reviewed.\n- The WebUI is currently **AI Generated** . It is mainly a viewer, so it is not considered a core part of the project.\n- The server is AI Generated and heavily human reviewed", "url": "https://wpnews.pro/news/charactermemory-memory-system-for-ai-characters", "canonical_source": "https://github.com/FrancescoCaracciolo/CharacterMemory", "published_at": "2026-10-06 14:01:00+00:00", "updated_at": "2026-10-06 14:21:10.448541+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["CharacterMemory", "FrancescoCaracciolo", "FastAPI", "Claude Desktop", "Cursor", "OpenAI", "MCP"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/charactermemory-memory-system-for-ai-characters", "markdown": "https://wpnews.pro/news/charactermemory-memory-system-for-ai-characters.md", "text": "https://wpnews.pro/news/charactermemory-memory-system-for-ai-characters.txt", "jsonld": "https://wpnews.pro/news/charactermemory-memory-system-for-ai-characters.jsonld"}}