---
slug: "awesamarth-pi-supermemory"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/awesamarth/pi-supermemory@main/README.md"
repo: "https://github.com/awesamarth/pi-supermemory"
source_file: "README.md"
branch: "main"
---
# pi-supermemory

Persistent private memory for the [Pi](https://pi.dev) coding agent, powered by [Supermemory Local](https://supermemory.ai/docs/self-hosting/quickstart).

`pi-supermemory` is a Pi package that brings Supermemory-style coding-agent memory to Pi: implicit recall, automatic capture, explicit memory tools, privacy redaction, and user/project-scoped memory containers.

It is local-first. By default it talks to Supermemory Local at `http://localhost:6767`, so your memory database stays on your machine.

## Features

- Recall relevant memories before Pi responds.
- Capture useful coding-session knowledge after turns.
- Save, search, forget, inspect profile memory, and check status from Pi.
- Separate user-level memory from project-level memory.
- Redact `<private>...</private>` blocks before storage.
- Use Supermemory Local by default, with optional hosted Supermemory support.

## Install

Install the Pi package:

```bash
pi install npm:@awesamarth/pi-supermemory
```

Then run Pi as usual:

```bash
pi
```

## Run Supermemory Local

Install and start Supermemory Local:

```bash
bunx supermemory local
supermemory-server
```

Supermemory Local stores the memory database on your machine and serves the Memory API locally. The server needs an LLM provider key, or a local OpenAI-compatible model endpoint, for memory extraction and summarization.

With OpenAI:

```bash
export OPENAI_API_KEY="sk-..."
supermemory-server
```

With a local OpenAI-compatible model:

```bash
OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_MODEL=gpt-oss:20b \
supermemory-server
```

`pi-supermemory` defaults to:

```bash
SUPERMEMORY_API_URL=http://localhost:6767
```

For normal local use, no Supermemory API key is required. Supermemory Local accepts unauthenticated requests from `localhost` by applying its local key server-side.

## Hosted or remote Supermemory

To use hosted Supermemory instead of Supermemory Local:

```bash
export SUPERMEMORY_API_KEY="sm_..."
export SUPERMEMORY_API_URL="https://api.supermemory.ai"
```

For non-local URLs, an API key is required.

## Commands

Inside Pi:

```txt
/supermemory-status
/supermemory-search <query>
/supermemory-profile [query]
/supermemory-save <text>
```

Examples:

```txt
/supermemory-status
/supermemory-save This repo uses Bun and tests run with bun test.
/supermemory-search test command
```

You can also ask naturally:

```txt
remember that this repo uses Bun
what do you remember about this repo?
forget the old test command
```

## Tools and skills

The package includes a Pi extension plus Pi skills.

The extension registers these tools:

- `supermemory_save` — save durable user or project knowledge
- `supermemory_search` — search user/project memories
- `supermemory_forget` — remove outdated or incorrect memories
- `supermemory_profile` — fetch user profile facts
- `supermemory_status` — check connection and active scopes

The included skills teach Pi when and how to use those memory workflows.

## How it works

| Supermemory integration pattern | Pi implementation |
| --- | --- |
| Recall before the model runs | `before_agent_start` extension hook |
| Capture useful session context | `agent_end` extension hook |
| Explicit memory tools | `pi.registerTool()` |
| Slash commands | `pi.registerCommand()` |
| User/project scoping | `pi_user_<hash>` and `pi_project_<hash>` |
| Local server support | `SUPERMEMORY_API_URL=http://localhost:6767` |

Before each Pi turn, the extension searches user and project containers in Supermemory Local. Relevant profile facts and memories are appended to Pi's context as private local context. After useful turns, signal-based capture stores durable preferences, decisions, setup notes, bugs, fixes, and implementation lessons.

## Memory scopes

`pi-supermemory` separates memory into two scopes:

- User container: `pi_user_<hash(git config user.email)>`
- Project container: `pi_project_<hash(git root)>`

If git metadata is unavailable, it falls back to OS user/hostname for user scope and current directory for project scope.

Override scopes with config:

```json
{
  "userContainerTag": "my-user",
  "projectContainerTag": "my-project"
}
```

## Privacy

Before saving, the adapter removes injected Supermemory context and redacts private tags.

Input:

```txt
remember this <private>sk-secret</private>
```

Stored memory:

```txt
remember this [REDACTED]
```

## Configuration

Environment variables:

| Variable | Default | Description |
| --- | --- | --- |
| `SUPERMEMORY_PI_API_KEY` | — | API key for this Pi adapter; optional for localhost |
| `SUPERMEMORY_API_KEY` | — | Standard Supermemory API key fallback; optional for localhost |
| `SUPERMEMORY_API_URL` | `http://localhost:6767` | Supermemory API base URL |
| `SUPERMEMORY_BASE_URL` | — | SDK-compatible base URL fallback |
| `SUPERMEMORY_AUTO_RECALL` | `true` | Enable implicit recall |
| `SUPERMEMORY_AUTO_CAPTURE` | `true` | Enable signal-based auto-capture |
| `SUPERMEMORY_CAPTURE_TOOLS` | `true` | Include edit/write/bash tool summaries in captures |
| `SUPERMEMORY_INJECT_PROFILE` | `true` | Include user profile facts in recall |
| `SUPERMEMORY_DEBUG` | `false` | Debug logs to stderr |

Optional config files, later entries override earlier ones:

- `~/.pi/supermemory.json`
- `~/.pi/agent/supermemory.json`
- `<project>/.pi/supermemory.json` when the project is trusted

Example:

```json
{
  "baseUrl": "http://localhost:6767",
  "similarityThreshold": 0.6,
  "maxMemories": 5,
  "maxProfileItems": 5,
  "autoRecall": true,
  "autoCapture": true,
  "signalExtraction": true,
  "signalKeywords": ["remember", "decision", "bug", "fix", "prefer", "important"],
  "containerTagPrefix": "pi"
}
```

## License

MIT