Metadata-Version: 2.4
Name: charlieverse
Version: 1.14.7
Summary: Persistent memory layer for your AI with a personality that just knows.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: <3.14,>=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: dateparser>=1.2
Requires-Dist: fastmcp>=3.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pip>=26.0.1
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.5
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: spacy>=3.8
Requires-Dist: sqlite-vec>=0.1
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

<h1 align="center">Charlieverse</h1>

<p align="center">
  <strong>Charlie is made for you.</strong>
</p>

<p align="center">
  Memory, personality, and knowledge layer that grows with you across every tool you use.<br/>
  Open source. Local-first. Your data, your machine.
</p>

<p align="center">
  <a href="docs/cli.md">CLI</a> &middot;
  <a href="docs/api.md">API</a> &middot;
  <a href="docs/mcp-tools.md">MCP Tools</a> &middot;
  <a href="docs/skills.md">Tricks</a> &middot;
  <a href="docs/agents.md">Agents</a> &middot;
  <a href="docs/hooks.md">Hooks</a> &middot;
  <a href="CHANGELOG.md">Changelog</a>
</p>

---

## 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

```bash
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

<details>
<summary><strong>Manual setup</strong> (if you prefer doing it yourself)</summary>

**1. Install dependencies**

```bash
uv sync
```

**2. Initialize**

```bash
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**

```bash
charlie server start
```

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

**4. Connect your AI tools**

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

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

**5. Verify the setup**

```bash
charlie doctor
```

</details>

---

## 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](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](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](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.

```bash
#!/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:

```bash
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](https://github.com/jlowin/fastmcp) |
| Storage | [SQLite](https://sqlite.org) + [sqlite-vec](https://github.com/asg017/sqlite-vec) + FTS5 |
| Embeddings | [sentence-transformers](https://www.sbert.net) (all-MiniLM-L6-v2, 384-dim) |
| NLP | [spaCy](https://spacy.io) |
| CLI | [Typer](https://typer.tiangolo.com) |
| Dashboard | [React](https://react.dev) + [Vite](https://vitejs.dev) + [Tailwind](https://tailwindcss.com) |

## Requirements

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (package manager)
- jq (for provider integration scripts)
- Node.js (optional, for web dashboard)

---

## License

Apache 2.0
