# 8mem

![8mem logo](docs/assets/logo.svg)

**Personal memory for AI — local-first, readable, portable.**

8mem is a Telegram-first personal memory system that remembers how you like replies, shows what it is using, and lets you correct it when it gets something wrong.

It is built for a simple but painful reality: every AI starts from scratch, and people repeat the same context, tone, preferences, and corrections every day.

8mem fixes that with a lightweight local stack:
- Markdown memory files
- JSONL event history
- SQLite structured facts
- optional `sqlite-vec` semantic retrieval
- Python memory logic

## 5-minute local quickstart

This is the fastest way to try 8mem locally. No cloud API key is required.

Today, the real supported runtime path is Ollama local.

### One-line install

The Type 1 public beta installer is:

```bash
curl -fsSL https://8mem.com/install.sh | bash
```

This public script contains no secrets and does not require GitHub authentication. It downloads a pinned 8mem wheel from `https://8mem.com/app/install/`, verifies its SHA256 checksum, installs it into a local virtual environment, runs setup, then runs `8mem doctor`.

When a terminal is available, the installer asks for the Telegram BotFather token, lets the user skip the public HTTPS webhook URL, and then detects OpenClaw. If `~/.openclaw/openclaw.json` is present, it wires the user's OpenClaw agent automatically and prints a receipt of the files changed. If OpenClaw is not present, 8mem remains usable as a standalone Telegram memory bot after `8mem start`.

When no terminal is available, such as CI or a strictly non-interactive shell, setup stays safe: it does not prompt, does not mutate OpenClaw files, and prints the follow-up command.

For source installs with repo access, use:

```bash
git clone https://github.com/tempomesh/8mem.git
cd 8mem
bash ./install.sh
```

The installer creates a local 8mem environment, installs the CLI, runs `8mem setup`, runs `8mem doctor`, and prints the exact next command to start the product.

If you do not want to run the installer and already have GitHub access configured, source install still works:

```bash
pip install git+https://github.com/tempomesh/8mem.git
```

When 8mem is published to PyPI, the intended install command is:

```bash
pip install 8mem
```

More install paths:
- [INSTALL.md](INSTALL.md)

Privacy details:
- [PRIVACY.md](PRIVACY.md)

### 1. Clone and install

```bash
git clone https://github.com/tempomesh/8mem.git
cd 8mem
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2. Start Ollama and pull one model

If Ollama is not installed yet, install it from [ollama.com](https://ollama.com).

```bash
ollama serve
```

In another terminal:

```bash
ollama pull qwen2.5:14b
```

### 3. Run guided setup

```bash
8mem setup --llm-model qwen2.5:14b
8mem doctor
```

`8mem setup` writes local runtime config under `~/.8mem/.env`, creates memory templates, and avoids manual file editing. During setup, users can set up Telegram now, skip Telegram and use the local UI first, or run setup later when they have a BotFather token and public URL. `8mem doctor` verifies runtime files, Telegram config/webhook if present, local model access, and `/v1/context` readiness.

### Optional: semantic retrieval

8mem's truth path does not depend on vector search. Markdown remains user-readable memory, SQLite facts remain active truth, JSONL remains audit truth, and Engram remains runtime export.

For larger memory sets, imports, and better related-memory recall, install the optional semantic layer:

```bash
pip install "8mem[semantic]"
```

When installed, `sqlite-vec` is used as a local retrieval helper. If it is missing, 8mem keeps working through exact SQLite/Markdown memory.

### Optional: Wire OpenClaw Agent

For Type 1 OpenClaw users, this command is also available if you installed non-interactively or want to re-apply the managed OpenClaw block:

```bash
8mem setup --mode openclaw
```

This reads the OpenClaw workspace from `openclaw.json` when available, appends managed 8mem blocks to OpenClaw `AGENTS.md` and `HEARTBEAT.md`, patches `openclaw.json` so Telegram inline buttons are enabled, and restarts `openclaw-gateway` when systemd is available.

For a remote primary 8mem runtime, pass the API URL and bearer key:

```bash
8mem setup --mode openclaw \
  --eightmem-api-url http://your-8mem-host:8787 \
  --eightmem-api-key your-remote-8mem-key
```

The setup does not hardcode your bearer key into OpenClaw files. The connected OpenClaw agent reads `EIGHTMEM_OPENCLAW_API_KEY` from `~/.8mem/.env` for remote primary memory, or `EIGHTMEM_LOCAL_API_KEY` for single-machine local installs.

To undo the OpenClaw wiring:

```bash
8mem uninstall --mode openclaw
```

### 4. Initialize and verify the model path

```bash
8mem test-ollama --model qwen2.5:14b --no-memory
```

### 5. Try the first real memory flow

```bash
8mem analyze examples/chat_export_sample.json
8mem ask-ollama "What do you know about how I like responses?" --model qwen2.5:14b
8mem start
8mem status
```

Then open:
- `http://127.0.0.1:8787`
- `http://127.0.0.1:8787/chat`

Use `8mem stop` to stop the background server. Use `8mem start --foreground` for foreground debugging.

If you installed 8mem as a user systemd service, update with:

```bash
git pull
bash ./install.sh
systemctl --user restart 8mem.service
8mem status
```

Without systemd, update with:

```bash
git pull
bash ./install.sh
8mem stop
8mem start
8mem status
```

If you want the full Telegram-style product flow, keep reading below.

## Why 8mem

Most AI memory products have the same problem:
- you cannot see what the AI knows about you
- you cannot correct it safely
- you cannot move that memory between tools

8mem is designed around the opposite principles:
- **visible**: memory is readable in plain files
- **correctable**: contradictions are surfaced, not hidden
- **portable**: memory can be reused across tools
- **local-first**: your memory stays on your machine

## What 8mem does

You talk normally in Telegram. 8mem picks up what matters, stores it, and uses it later.

Example:

```text
You:   Keep my work replies concise
8mem:  I'll keep my work replies concise.
       Saved to memory: Keep my work replies concise.

You:   Don't use emojis in client messages
8mem:  I won't use emojis in client messages.
       Saved to memory: Don't use emojis in client messages.

You:   Reply like me: can we move tomorrow's meeting
8mem:  Can we move tomorrow's meeting? Share a time that works for you.
```

You can also ask:
- `What do you remember about me?`
- `What are you using right now?`
- `What changed about me?`
- `Show me the normal version vs mine`

## Demo

### Passport

The clearest artifact in 8mem is `/passport`: a visible summary of the memory it is actively using for you.

![8mem passport demo](docs/assets/8mem_passport_demo.gif)

### Telegram flow

![8mem Telegram demo](docs/assets/8mem_telegram_demo.gif)

## The best product surfaces

### `/passport`
Shows the memory 8mem is actively using for you.

![8mem trust demo](docs/assets/8mem_trust_demo.gif)

### `/compare`
Shows a standard answer next to a memory-shaped answer so you can see whether memory is actually improving output.

### `What changed about me?`
Shows recent memory changes in a human-readable way.

These three surfaces make memory visible instead of hidden.

## Product shape today

### Telegram-first
- natural memory capture
- memory-aware replies and drafts
- recall, compare, passport, recent changes
- contradiction resolution with inline choices
- undo and reset

### Web UI
- dashboard
- mirror
- files
- editor
- inbox
- export

### Storage and logic
- `Markdown` for human-readable memory
- `JSONL` for append-only event history
- `SQLite` for structured facts and mirrored events
- optional `sqlite-vec` for local semantic search
- Python rules for contradiction and trust logic

## Features

### Natural memory capture
- save obvious preferences without requiring `Remember:`
- save obvious corrections without requiring `Correct:`
- still support explicit power-user commands
- ignore ambiguous statements instead of saving them aggressively

### Memory visibility
- `What do you remember about me?`
- `What are you using right now?`
- `/passport`
- `What changed about me?`
- `8mem forget <text>` to remove a saved memory with confirmation

### Memory-aware output
- `Reply like me: ...`
- `Draft: ...`
- `/compare ...`

### Trust and control
- contradiction detection
- contradiction resolution
- undo last memory change
- reset memory

### Natural routing
- typo-tolerant recall
- natural aliases for compare, recall, draft, and memory view
- onboarding with `/start`, `help`, and `what can you do`

## How it works

Short flow:

```text
User
  -> Telegram
  -> ui/app.py webhook
  -> telegram_service
  -> exact / fuzzy / LLM intent router
  -> memory_service
  -> Markdown + JSONL + SQLite + optional sqlite-vec
  -> response assembly
  -> ui/app.py sender
  -> Telegram
  -> User
```

### The architecture

| Layer | Component | Responsibility |
|---|---|---|
| Interface | Telegram + web UI | Receive input, present output |
| Routing | `telegram_service.py` | Intent routing, UX shaping |
| Memory logic | `memory_service.py` | Normalization, recall, compare, trust logic |
| Storage | Markdown + JSONL + SQLite | Readable memory, event history, structured facts |
| Retrieval | optional `sqlite-vec` | Semantic memory lookup when installed |
| Ingestion | `ingestion.py` + `import_cache.py` | Chunking, candidate fact extraction, apply-to-memory flow |

## Install

### Local-only path

```bash
git clone https://github.com/tempomesh/8mem.git
cd 8mem
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
```

For the supported local setup, you only need:
- `OLLAMA_BASE_URL`
- `DEFAULT_LLM_FALLBACK_MODEL`

Preferred path:

```bash
8mem setup --llm-model qwen2.5:14b
8mem doctor
```

Ignore the cloud-provider placeholders in `.env.example` for now. They are future-facing, not the current public runtime path.

## Quickstart

### Fastest first success

```bash
8mem setup --llm-model qwen2.5:14b
8mem doctor
8mem test-ollama --model qwen2.5:14b --no-memory
8mem analyze examples/chat_export_sample.json
8mem ask-ollama "What do you know about how I like responses?" --model qwen2.5:14b
8mem start
8mem status
```

Open:
- `http://127.0.0.1:8787`
- `http://127.0.0.1:8787/chat`

### Import and mirror flow

```bash
8mem analyze examples/chat_export_sample.json
8mem mirror
8mem export-context -o context.txt
```

## Telegram examples

### Save a preference
```text
Keep my work replies concise
```

### Save a correction
```text
Don't use emojis in client messages
```

### Recall
```text
What do you remember about me?
```

### Memory view
```text
What are you using right now?
```

### Compare
```text
Compare the normal version with mine: answer this client: Can we move the meeting to Friday?
```

### Draft in my style
```text
Reply like me: can we move tomorrow's meeting
```

### Recent changes
```text
What changed about me?
```

## Power-user commands

Core commands:
- `Remember: keep answers concise`
- `Correct: do not use emojis`
- `What do you know about me`
- `Draft: write a founder update in my style`
- `reset memory`
- `undo last memory change`

Profile and comparison:
- `/passport`
- `/compare Draft: write a founder update in my style`
- `/compare Draft: recommend a laptop in my style`
- `/compare Reply: answer this client in my style: <paste client message>`
- `/compare Summarize: summarize this update in my style`

## Memory files

Stored in `~/.8mem/memory/`:

- `IDENTITY.md`
- `BELIEFS.md`
- `PREFERENCES.md`
- `CORRECTIONS.md`
- `EVOLUTION.md`
- `DECISIONS.md`
- `.memory_events.jsonl`

Markdown files remain the readable source of truth.

## Repo structure

```text
src/eightmem/
  cli/
  core/
  analyzers/
  importers/
  mirror/
  services/
  ui/
examples/
tests/
docs/
```

## Screenshots

Dashboard

![8mem dashboard](docs/assets/dashboard.png)

Memory editor

![8mem memory editor](docs/assets/editor.png)

Telegram demo

![8mem demo flow](docs/assets/8mem_telegram_demo.gif)

## Current status

- Phase 4 complete
- Telegram product loop in place
- `81` tests passing in the latest verified product pass

The core loop now includes:
- natural memory capture
- recall
- passport
- compare
- recent changes
- conflict resolution
- undo
- reset
- memory-aware draft/reply

## What makes 8mem different

1. **Readable memory**
   Every memory is a file you can open and verify.

2. **Visible trust**
   You can see what 8mem knows, what it is using, and what changed.

3. **Portable memory**
   Memory is not trapped in one black-box product.

4. **Lightweight architecture**
   No heavy graph stack required to get useful memory behavior.

## Roadmap

Near-term:
- launch cleanup
- packaging cleanup
- public repo polish
- stronger `/passport` sharing story

Longer-term:
- broader import flows
- richer memory standard / portability story
- cross-agent memory propagation story

## Contributing

PRs are welcome. Keep changes:
- local-first
- readable
- test-backed
- memory-safe
