Free Beta
Home / Docs / Memory System

Memory System

Persistent Memory · Per-Character · Full-Text Search

Overview

TokForge remembers things about you across conversations. Instead of repeating yourself, your AI remembers your preferences, goals, constraints, and the knowledge you share with it. All memory stays on your device — nothing is sent to the cloud.

The memory system stores three types of information per character:

Memory Facts

Individual pieces of information like "prefers formal language", "is a software engineer", or "lives in Austin". Facts can be manually added by you, automatically extracted from conversations, or imported. Important facts are always included in the AI's context window, so they're never forgotten.

Knowledge Graph

Structured relationships between entities. When you say "I like coffee", TokForge creates a connection: You → prefers → coffee. These relationships build up over time into a web of knowledge about you. The more you mention something, the stronger the connection becomes.

Reference Documents

Import text documents as background knowledge for a character. Perfect for giving a character context about a D&D campaign setting, a project brief, your personal notes, or anything else that should be part of their understanding about you.

Memory Facts

Facts are the core of TokForge's memory. They're individual snippets of information about you, your preferences, and your context.

What Gets Stored

Examples of facts TokForge might learn or store:

  • Preferences: "prefers coffee over tea", "likes structured agendas"
  • Identity: "is a software engineer", "lives in Austin, Texas"
  • Goals: "learning Japanese", "wants to build a side project"
  • Constraints: "avoids dairy", "cannot work past 6pm"
  • Relationships: "close friends with Alex", "works with Sarah"
  • Issues: "experienced a bug with model loading", "having trouble with authentication"

How Facts Are Created

Automatic extraction: When you chat naturally with a character, TokForge listens for memorable information and extracts facts automatically. No work required.

Manual addition: Open the Memory screen and add facts directly via the "+" button. These facts are automatically pinned so they won't be removed.

Import: Bring in facts from external sources if needed.

Importance Scoring

TokForge automatically scores facts by importance (0-10 scale). Facts about critical preferences, constraints, or goals score higher. More important facts are always kept in the AI's context window, ensuring they're never forgotten. Less important facts that haven't been used in a while are automatically cleaned up after 90 days (though you can pin important ones to protect them).

Managing Facts

  • Pin facts: Protect important facts from auto-cleanup. Pinned facts always stay in memory.
  • Archive facts: Hide old facts instead of deleting them. Archived facts won't be used in conversations but are kept for your records.
  • Search facts: Use full-text search to find any fact by keyword.
  • Edit facts: Update fact wording anytime.
  • Delete facts: Permanently remove facts you no longer need.

Knowledge Graph

The knowledge graph is a structured map of relationships extracted from your facts and conversations. It captures who knows whom, what you prefer, where you live, what you own, and more.

How It Works

When you tell a character something like:

  • "I live in New York" → You → lives_in → New York
  • "I'm a software engineer" → You → works_as → software engineer
  • "I like coffee" → You → prefers → coffee
  • "Sarah is my colleague" → You → works_with → Sarah

These relationships strengthen over time. If you mention coffee five times, the "prefers coffee" connection gets stronger. The AI sees these patterns and uses them to better understand your preferences and context.

Viewing the Knowledge Graph

The Memory screen includes a Knowledge tab where you can:

  • Browse relationships in list view: See all "You prefers X", "You lives in Y", etc., organized by entity
  • Visualize as a graph: See a force-directed network diagram of entities and their relationships. Larger nodes mean more mentions.
  • Explore connections: Tap nodes to highlight connected relationships

Document Import

Import text documents to give a character background knowledge. Documents are stored locally and searched when needed.

Use Cases

  • D&D campaigns: Import campaign setting descriptions, lore, NPC backstories
  • Project briefs: Share project requirements, design docs, or architecture notes
  • Personal knowledge: Import family history, travel notes, or personal reference materials
  • Technical docs: Add API documentation, code libraries, or software guides

How to Import

  1. Open the Memory screen for a character
  2. Go to the Documents tab
  3. Tap "Import Document" and select a text file
  4. The document is chunked and indexed for fast retrieval

Managing Documents

  • View document title, chunk count, and total characters
  • Delete documents anytime without affecting other memory
  • Each character has its own document library

Memory Screen UI

The dedicated Memory screen is where you browse, search, and manage all memory for a character.

Three Tabs

Facts Tab: Browse all your memory facts. Pinned facts appear at the top. Search by keyword, add new facts with the floating "+" button, or tap a fact to edit it. Long-press any fact to toggle pin status. Archive old facts when you're done with them.

Knowledge Tab: View the relationship graph. Switch between list view (organized by subject/entity) and graph view (visual network). In graph view, tap nodes to see connected relationships. All relationships are automatically extracted from facts and conversations.

Documents Tab: Manage imported reference documents. See title, chunk count, and size. Delete documents individually when no longer needed.

Character Selection

At the top of the Memory screen, select which character's memory you want to view. Each character has its own separate memory space — facts, knowledge graphs, and documents are completely isolated.

Search

Use the search field to find facts by keyword. Search is instant and works across all your facts using full-text search. Search is case-insensitive and matches on any part of fact text.

How Memory Works in Chat

Memory is automatic. When you chat, TokForge is always working in the background:

  1. Relevant memories are retrieved: When you send a message, TokForge automatically finds memories most relevant to your conversation
  2. Memories are included in context: The AI sees your top facts, knowledge relationships, and relevant documents in its context window
  3. Conversations feel continuous: Instead of starting fresh each time, it feels like you're picking up where you left off
  4. New memories are extracted: As you chat, TokForge continuously listens for new memorable information to store

All of this happens locally on your device. No memory data ever leaves your phone or tablet.

Managing Your Memory

Pinning Facts

Pin the facts that matter most. Pinned facts:

  • Are always included in the AI's context
  • Never get auto-deleted during cleanup
  • Appear at the top of the Facts list

Manually added facts are automatically pinned by default.

Archiving Facts

Archive facts instead of deleting them. Archived facts:

  • Won't be used in conversations
  • Are hidden from the main Facts list
  • Are kept for your records
  • Can be unarchived anytime

Automatic Cleanup

TokForge automatically cleans up stale, low-importance facts that are older than 90 days. Cleanup protects you from:

  • Memory bloat from forgotten snippets
  • Outdated information cluttering context
  • Inconsistent AI behavior from conflicting facts

Protected facts never get deleted: Pinned facts and high-importance facts are always protected, no matter how old they are.

Per-Character Isolation

Each character has completely separate memory. You can have very different personas with different facts, preferences, and knowledge. Switch characters in the Memory screen to manage each one independently.

Privacy & Storage

Local Storage

All memory data — facts, knowledge edges, documents — is stored locally in TokForge's encrypted database on your device. Nothing is sent to TokForge servers or the cloud.

Persistence

Memory survives app restarts, device reboots, and everything in between. Once a fact is stored, it's yours permanently (until you delete it or it's auto-cleaned).

Data Control

You have complete control over your memory:

  • Delete individual facts anytime
  • Clear all memory for a character at once
  • Export your memory data for backup or analysis
  • Archive instead of delete if you want to keep records

No Cloud Sync

Memory is entirely device-local. There's no cloud sync, cloud backup, or any transmission of memory data outside your device. If you switch devices, you'll need to rebuild memory on the new device, but your original device data remains untouched.

API Access

For advanced users and integrations, memory can be managed programmatically via the MetricsService API. See the API Reference for complete endpoint documentation.

Available Operations

  • Create facts: Add new facts for a character programmatically
  • Retrieve facts: Get all facts or search by keyword
  • Update facts: Modify fact content or importance
  • Pin/unpin facts: Control which facts are always used
  • Delete facts: Remove facts individually
  • View knowledge graph: Get all relationship edges for a character
  • Manage documents: Import, list, and delete reference documents
  • Trigger cleanup: Manually run stale fact cleanup

Authentication

All memory API endpoints require Bearer token authentication. Get your token from Settings → Advanced → Metrics Server → Metrics Auth Token.

Example: List all facts for a character via API: 
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8088/memory/facts?character_id=1

See the API documentation for complete examples and all available endpoints.