长期记忆系统

🚀 Quick Start

<ins>Step 1.</ins> Open a terminal.

• Mac: Cmd + Space, type Terminal
• Linux: Ctrl + Alt + T
• Windows: open PowerShell

&nbsp;

<ins>Step 2.</ins> Paste this and press Enter:

Mac / Linux:

curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.ps1 | iex

&nbsp;

<ins>Step 3.</ins> Wait 3-5 minutes for installation.

&nbsp;

<ins>Step 4.</ins> Quit Claude completely and reopen it (Mac: Cmd+Q, Windows: right-click the Claude tray icon → Quit).

&nbsp;

<ins>Step 5.</ins> Type "Set up TrueMemory" and pick Edge, Base, or Pro.

&nbsp;

That's it. TrueMemory remembers your conversations automatically from here.

• Switch tiers: tell Claude "switch to Pro" or "switch to Base"
• Update: run uv tool upgrade truememory in Terminal, then restart Claude
• Uninstall: run uv tool uninstall truememory

⭐ Tip: Quit your Claude sessions when you're done prompting. TrueMemory's memory hook runs when the session ends, so it can capture and store the full conversation.

<details> <summary><b>Click here for the advanced setup guide ▸</b></summary>

What the installer does

Installs uv (Astral's Python tool manager) if needed, fetches a managed Python 3.12, installs TrueMemory with all tier models into an isolated tool environment, registers the MCP server, wires up lifecycle hooks, and merges instructions into ~/.claude/CLAUDE.md. Your system Python is never touched. No sudo, no venvs, no pip struggle.

Audit the script

It's ~200 lines of shell, no sudo, stays entirely under $HOME:

curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh -o install.sh && less install.sh && sh install.sh

Python library (for developers)

If you're embedding TrueMemory in your own Python project (requires Python 3.10+):

pip install truememory

pip install installs the Python library only. It does NOT register the MCP server, install hooks, or configure Claude. For Claude Code / Claude Desktop, always use the curl | sh installer above.

```python from truememory import Memory

m = Memory() m.add("Prefers dark mode and TypeScript", user_id="alex") m.add("Allergic to peanuts", user_id="alex")

results = m.search("What are Alex's preferences?", user_id="alex") print(results[0]["content"])

Evaluation config

All benchmarks use the same eval pipeline. Nothing is hidden.

Full details: LoCoMo | LongMemEval | BEAM

---

🐍 Python API

```python from truememory import Memory

m = Memory()

❓ FAQ

My session doesn't seem to know anything about me. What's wrong?

On your first session, TrueMemory runs setup. It won't recall memories until setup is complete. After that, every new session automatically searches your memory and injects up to 25 relevant facts as context. If memories still aren't loading, check that the MCP server is connected (truememory_stats) and that you have memories stored (truememory_search with a broad query).

Where is my data stored? Is anything sent to the cloud?

Everything lives locally in a single SQLite file at ~/.truememory/memories.db. Edge and Base tiers make zero external network calls. Pro tier sends only your search query text to an LLM API for HyDE expansion. Your memories themselves are never transmitted. Back up anytime with cp ~/.truememory/memories.db backup.db.

How do I switch tiers (Edge → Base → Pro)?

Call truememory_configure(tier="base") (or "pro") in any session, or run truememory-ingest upgrade-tier base from the terminal. All tier models are included in the standard install — switching just re-embeds your existing memories with the new model. Pro also needs an API key for HyDE query expansion.

I switched tiers and search results seem off. How do I fix it?

After a tier switch, TrueMemory re-embeds all memories with the new model. If this was interrupted, run truememory_configure(tier="...") again to retry. If results are still degraded, you can delete ~/.truememory/memories.db and start fresh. Your conversations are still in your chat history and will be re-extracted.

Do I need Python installed?

No. The recommended install (curl -LsSf .../install.sh | sh) uses uv to manage a sandboxed Python 3.12. Your system Python is never touched. To uninstall cleanly: uv tool uninstall truememory.

Does TrueMemory collect telemetry?

TrueMemory collects anonymous usage telemetry to help us understand how the product is used and improve it. We track which tools are called and how often, session counts, and basic platform info (OS, tier, version). We never track your memory content, search queries, file paths, or API keys. Telemetry is on by default. To opt out:

export TRUEMEMORY_TELEMETRY=off

---

Find me on X @Building_Josh · Follow us @Sauron_Labs

---