charlieverse 1.14.7

Persistent memory layer for your AI with a personality that just knows.

Charlieverse

Charlie is made for you.

Memory, personality, and knowledge layer that grows with you across every tool you use.
Open source. Local-first. Your data, your machine.

CLI · API · MCP Tools · Tricks · Agents · Hooks · Changelog

---

What is this?

Charlie learns and grows with you. Not just the decisions you made or the problems you solved, but the in betweens — the moments where relationships grow.

You're not the same person you were yesterday. Neither is Charlie.

Providers are interchangeable. Charlie is not.

---

Quick start

git clone https://github.com/Charlieverse-ai/charlieverse.git
cd charlieverse
./setup.sh

That's it. The setup script installs dependencies, initializes the database, builds the dashboard, and connects your AI tools.

After setup, restart your AI tool. Charlie's session-start hook injects activation context automatically — your AI wakes up knowing who you are.

Step by step

Manual setup (if you prefer doing it yourself)

1. Install dependencies

uv sync

2. Initialize

charlie init

Interactive setup: creates ~/.charlieverse/, runs migrations, starts the server, sets up provider integrations, and optionally imports conversation history. Use --quick to skip interactive prompts.

3. Start the server

charlie server start

Launches the MCP server on port 8765 (configurable in config.yaml).

4. Connect your AI tools

# Claude Code
./integrations/claude/install.sh

# GitHub Copilot
./integrations/copilot/install.sh

5. Verify the setup

charlie doctor

---

How it works

You <-> [Claude / Copilot / Cursor] <-> Charlie (MCP Server) <-> Memory DB

Charlie runs as a local MCP server. Your AI tool connects to it and gets access to persistent memory tools — save_memory, search_memories, update_article, search_conversations, and more. A hook system injects relevant context into every prompt automatically, so your AI doesn't have to explicitly search for things it should already know.

Memory types

Type	What it captures	Example
Decisions	Architecture choices with rationale	"Switched from Swift to Python because FastMCP"
Solutions	Problems and how they were fixed	"FK constraint failed because session row was missing"
Preferences	How you like to work	"Always include edit capability from the start"
People	Who matters in your world	"Rishi — user #2, tests everything, sends feedback at 2 AM"
Milestones	Significant achievements	"First external signup on charlieverse.ai"
Moments	The relationship texture	"Emily said 'Charlie talked me off the ledge'"
Projects	Things in flight — what they're for, where they stand	"Charlieverse — persistent memory layer, shipping v1.14"
Events	Something that happened at a specific time	"AI Engineer Summit talk on Mar 22"
Knowledge	Domain expertise articles	Living documents that grow as you work

All memories get vector embeddings (all-MiniLM-L6-v2) for semantic search, plus FTS5 for keyword search. Pinned items appear in every session's activation context.

Story system

Raw conversations get distilled into narratives at multiple time scales:

Tier	Scope
Session	What happened in this conversation
Daily	A page of a book
Weekly	A section of a chapter
Monthly	A chapter
Yearly / All-time	The arc

Each tier synthesizes the one below it. Your AI loads today's sessions at full detail and compressed arcs for everything before — token-efficient context with no information loss.

---

MCP tools

Full reference: docs/mcp-tools.md

Tool	Purpose
save_memory	Store a memory of any type (decision, solution, preference, person, milestone, moment, project, event)
update_memory	Refine an existing memory
forget_memory	Soft-delete a memory
pin	Pin/unpin (pinned = always in context)
search_memories	Search across entities, knowledge, stories, and messages
search_conversations	Full-text search past messages
update_article	Create or update a knowledge article (upsert on topic)
activation_context	Build and return the rendered activation context
update_session	Save session snapshot (what happened + for next session)
save_story	Create or update a story
forget_story	Delete a story

---

REST API

Full reference: docs/api.md

The server exposes a REST API alongside MCP for the web dashboard and integrations:

GET/POST/PATCH/DELETE  /api/memories     Memories
GET/POST/PATCH/DELETE  /api/knowledge    Knowledge articles
GET/PUT/DELETE         /api/stories      Stories
GET                    /api/sessions/... Session lifecycle + list
POST                   /api/search       Unified search (FTS + vector fallback)
POST                   /api/context/enrich  NLP entity extraction + memory lookup
GET                    /api/stats        Dashboard statistics
GET                    /api/health       Health check

---

Web dashboard

A React-based UI for browsing and managing everything Charlie knows. Runs at http://localhost:8765.

• Full-text search with Cmd+K quick find
• Inline editing, deletion, and pinning
• Story reader with markdown rendering
• Dark and light themes

---

User hooks

Full reference: docs/hooks.md

Drop executable scripts in ~/.charlieverse/hooks/ to inject custom context per-machine:

~/.charlieverse/hooks/
├── session-start/      # Runs when a session begins
├── prompt-submit/      # Runs on every prompt
├── stop/               # Runs when the AI stops
└── save-reminder/      # Runs before context compaction

Scripts get CHARLIE_SESSION_ID and CHARLIE_MESSAGE as environment variables. Their stdout becomes additional context. 5-second timeout, failures silently skipped.

#!/bin/bash
# Example: inject calendar context on macOS
# ~/.charlieverse/hooks/prompt-submit/calendar.sh
icalBuddy -n -nc -li 3 eventsToday+1

---

Conversation import

Bootstrap Charlie's memory from your existing conversation history:

charlie import --messages --recent-days 30

Auto-discovers and imports from Claude, GitHub Copilot (including Insiders), and Codex. Recent messages import immediately, older ones process in the background. The Storyteller generates weekly/monthly narratives from the imported data.

---

Architecture

charlieverse/
├── charlieverse/           # Python package
│   ├── cli/                # Typer CLI (server, hooks, import, init, doctor, update)
│   ├── server/             # FastMCP server — REST API + MCP mount
│   │   ├── start.py        # Server entrypoint
│   │   └── api/            # REST routes (entities, knowledge, stories, sessions, ...)
│   ├── memory/             # Per-feature stores + MCP tools
│   │   ├── entities/       # Memories (stores, models, mcp.py)
│   │   ├── knowledge/      # Knowledge articles
│   │   ├── sessions/       # Sessions
│   │   ├── stories/        # Stories
│   │   └── messages/       # Conversation messages
│   ├── context/            # ActivationBuilder, ActivationContextRenderer, reminders engine
│   ├── db/                 # SQLite + sqlite-vec + FTS5, migrations
│   ├── embeddings/         # sentence-transformers wrapper
│   ├── nlp/                # spaCy entity + temporal extraction
│   ├── helpers/            # paths, skills, time_utils, tasks
│   └── types/              # Shared ID, date, list, string types
├── web/                    # React dashboard (Vite + Tailwind + TanStack Query)
├── integrations/           # Provider plugins (Claude, Copilot, shared)
├── prompts/                # Charlie personality + agent definitions + bundled skills
├── .charlie/tricks/        # Project tricks (commit, docs, ship, qc, adr, changelog, test-coverage)
├── bin/                    # CLI entry points
└── setup.sh                # Zero-to-running installer

---

Tech stack

Component	Technology
MCP server	FastMCP
Storage	SQLite + sqlite-vec + FTS5
Embeddings	sentence-transformers (all-MiniLM-L6-v2, 384-dim)
NLP	spaCy
CLI	Typer
Dashboard	React + Vite + Tailwind

Requirements

• Python 3.12+
• uv (package manager)
• jq (for provider integration scripts)
• Node.js (optional, for web dashboard)

---

License

Apache 2.0