Digital Persona Memory App

Builds a searchable memory bank from PDF content and exposes it as an MCP tool.

Add it as an MCP server in your favorite AI client (eg: LM Studio) with the included system prompt and chat with your heroes, historical figures, or any collection of PDF content.

Example personas are included for Karl Marx and Friedrich Engels. The personas are built from every work both figures ever published. You can chat, ask them questions, or even debate them as though they were still alive and they'll respond based on their own publicly available works.

Alternative uses include adding your school textbooks in PDF format and asking them questions. No more finding that one page, just ask it to explain whatever you want to know.

A modified version of this app is used to bring Facebook users to life as Digital Personas using their exported Facebook data.

What This App Does

• extracts and indexes persona content from PDF-derived JSON sections
• builds per-person Chroma memory databases
• serves an MCP search tool with semantic ranking plus recency scoring
• supports multiple personas by adding folders under pdf/

Core Features

• parser/ contains PDF parsing tools to turn PDF persona text into JSON section files.
• 2_build_memory.py embeds documents and builds a Chroma memory DB.
• 3_avatar_mcp.py exposes search_my_memory() as an MCP tool.
• --name lets you create and query separate memory databases for different personas.
• config.json centralizes paths, embedding server settings, memory DB defaults, and search tuning.

Project Files

• 1_prep_data.py: Prepare imported JSON data and normalize text for memory import.
• 2_build_memory.py: Build the Chroma memory database with optional persona selection.
• 3_avatar_mcp.py: Run the MCP server and query the selected memory database.
• config.json: Configuration for PDF sources, embeddings, memory DB paths, and search settings.
• parser/: PDF downloader and parser utilities for creating JSON section files from PDFs.

Python Requirements

Install dependencies in your virtual environment:

pip install -r requirements.txt

Data Layout

PDF Persona Support

Each persona owns a directory under pdf/. For example:

• pdf/marx/ (Karl Marx persona, included as a sample)
• pdf/engles/ (Friedrich Engels persona, included as a sample)

Memory DB Layout

The memory database lives under the base path in config.json. When using --name, a separate collection directory is created:

• avatar_memory_db/marx/
• avatar_memory_db/engles/

Each persona DB contains Chroma persistence files plus a document_index.json.

LM Studio Setup

Before building or querying memory:

1. Start LM Studio's Local Server.
2. Load the embedding model configured in config.json.
3. Confirm embeddings.api_base matches the Local Server URL.

End-to-End Workflow

1) Add persona-specific PDF data or formatted JSON sections

Option 1: Add PDF files in pdf/<persona>/ and run the parser tools in parser/ to create JSON section files in pdf/<persona>/json/.

You will need to edit the parser tools to meet your specific PDF structure and content. The included parser/ tools are a starting point for common PDF layouts.

Option 2: Add JSON section files directly in pdf/<persona>/json/. The JSON files should be structured as:

{
  "sections": [
    {
      "title": "Section Title",
      "text": "Section text content...",
      "timestamp": "2024-01-01T00:00:00Z" // Timestamp is optional but recommended for recency scoring
    },
    ...
  ]
}

2) Prepare JSON data for ingestion

python 1_prep_data.py

This will normalize the text and prepare the JSON sections for embedding. It will prompt you to select a persona if multiple are present.

3) Build the memory DB

Option 1: Build default collection (no persona name specified. Will use config.json default collection name):

python 2_build_memory.py

Option 2: Build a named persona collection:

JSON files for Karl Marx and Friedrich Engels are included as examples.

python 2_build_memory.py --name marx

python 2_build_memory.py --name engles

4) Start the MCP server

Option 1: Run the default DB server:

python 3_avatar_mcp.py

Option 2: Run a named persona DB server:

python 3_avatar_mcp.py --name marx

python 3_avatar_mcp.py --name engles

The exposed MCP tool is:

search_my_memory(topic, num_results=...)

Search Behavior

Results are ranked by:

• semantic similarity from embeddings
• an optional recency boost

Tune behavior in config.json:

• search.default_num_results
• search.candidate_multiplier
• search.recency_half_life_days
• search.recency_weight_alpha

Troubleshooting

• No memory results:
  • Confirm pdf/<persona>/json/ files exist.
  • Confirm prepared_documents.json exists in the persona folder (or whatever filename you specified in config.json).
  • Rebuild the memory DB.
• Collection or DB errors:
  • Verify memory_db.path and collection_name in config.json.
  • Use --name consistently for build and server.
• LM Studio errors:
  • Confirm the Local Server is running with embedding model loaded.
  • Check embeddings.api_base, and ensure the model name in config.json match LM Studio's model name.
• Long build times:
  • Large persona data can take 5-10+ minutes depending on hardware and embedding throughput.

Screenshot of this in action

<img width="1408" height="751" alt="image" src="https://github.com/user-attachments/assets/c374217b-79eb-4d63-8d56-7f8396264fd8" />