8mem 0.1.1

8mem: local-first memory layer for AI chats

8mem

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:

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:

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:

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

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

pip install 8mem

More install paths:

• INSTALL.md

Privacy details:

• PRIVACY.md

1. Clone and install

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.

ollama serve

In another terminal:

ollama pull qwen2.5:14b

3. Run guided setup

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:

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:

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:

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:

8mem uninstall --mode openclaw

4. Initialize and verify the model path

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

5. Try the first real memory flow

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:

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

Without systemd, update with:

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:

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.

Telegram flow

The best product surfaces

/passport

Shows the memory 8mem is actively using for you.

/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:

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

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:

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

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

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

Telegram examples

Save a preference

Keep my work replies concise

Save a correction

Don't use emojis in client messages

Recall

What do you remember about me?

Memory view

What are you using right now?

Compare

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

Draft in my style

Reply like me: can we move tomorrow's meeting

Recent changes

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

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

Screenshots

Dashboard

Memory editor

Telegram demo

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