> ## Documentation Index
> Fetch the complete documentation index at: https://docs.negentro.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Install and manage the PiyAPI Claude Code plugin for persistent cross-session memory. Learn commands, scopes, and troubleshooting in minutes.

Persistent cross-session memory for Claude Code.

Connect the PiyAPI plugin to your Claude Code environment to persist relevant bitemporal context across sessions and retrieve it on demand.

> **Current plugin version:** `v1.2.0`

## Prerequisites

<Steps>
  <Step title="PiyAPI API key">
    Required for authentication. Export this as `PIYAPI_API_KEY`.
  </Step>

  <Step title="Supported agent environment">
    The Claude Code CLI must be installed and accessible on your `$PATH`.
  </Step>

  <Step title="Runtime dependencies">
    Node.js 18+ and the `piyapi-cli`.
  </Step>
</Steps>

## Quick Start

To install the plugin, bind it to your Claude Code session, and confirm the connection:

<CodeGroup>
  ```bash Install theme={null}
  export PIYAPI_API_KEY="sk_live_your-api-key"
  piyapi plugin install claude-code
  ```

  ```bash Verify theme={null}
  piyapi plugin status
  ```
</CodeGroup>

**Setup Flow:** `1. Install` -> `2. Configure` -> `3. Restart agent` -> `4. Verify`

## Managing the Plugin

Use the CLI to manage the plugin lifecycle:

```bash theme={null}
# Install / Update / Uninstall / Status
piyapi plugin install claude-code
piyapi plugin update claude-code
piyapi plugin uninstall claude-code
piyapi plugin status
```

## What You Can Do

* **Automatic memory**: Captures relevant context from coding sessions in the background.
* **Commands**: Exposes explicit CLI commands for searching, checking status, forgetting, and pausing/resuming memory capture.
* **Search tool**: Query previous sessions and retrieve relevant context on demand via the UnifiedScorer.
* **Sidekick agent**: Spin up an isolated investigation or implementation workflow while preserving the primary working context.

## Commands

| COMMAND | DESCRIPTION |
| :- | :- |
| `/memory:search` | Search memories from earlier sessions. |
| `/memory:status` | Check current memory and configuration state. |
| `/memory:forget` | Delete or forget selected memories. |
| `/memory:pause` | Pause automatic memory capture. |
| `/memory:resume` | Resume automatic memory capture. |
| `/memory:remember` | Explicitly force-capture a specific input. |

## Search Tool

Use the search tool to query prior sessions and retrieve context bounded by relevance and scope.

```javascript theme={null}
memory.search('authentication flow', { scope: "project" })
```

```json theme={null}
{
  "results": [
    {
      "memory_id": "8a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "content": "Authentication uses JWT tokens for the main API...",
      "score": 0.91
    }
  ]
}
```

## Sidekick Agent

The sidekick agent handles isolated investigation or implementation work in a separate context, then returns its findings to the main agent without polluting the primary working memory.

Workflow: `Main Agent` -> `Sidekick` -> `Investigation` -> `Result` -> `Main Agent`

## How It Works

<Steps>
  <Step title="Capture">
    Records relevant activity from the agent session.
  </Step>

  <Step title="Flush">
    Sends captured context to the PiyAPI engine after meaningful interaction boundaries.
  </Step>

  <Step title="Extract">
    Parses useful project context, architectural decisions, constraints, and preferences.
  </Step>

  <Step title="Recall">
    Retrieves relevant bitemporal memories during subsequent sessions.
  </Step>
</Steps>

Architecture flow:

```text theme={null}
Agent Session -> Capture -> PiyAPI Memory -> Extract -> Store -> Recall -> Next Session
```

## Memory Scoping

Memory is strictly scoped between shared project context and personal context. Relevant overlap is surfaced dynamically during retrieval via Context Assembly.

Data flow:

```text theme={null}
Personal Memory + Project Memory + Session Context -> Context Assembly (Retrieve, Filter, Combine) -> Relevant Context
```

## Search Scope

| SCOPE | RETURNED CONTEXT |
| :- | :- |
| `repo` | Project-wide memory. |
| `dir` | Directory-specific memory. |
| `user` | Personal user memory. |
| `session` | Current task memory. |

*Example: Setting scope to `dir` restricts retrieval strictly to memories captured within the current working directory.*

## Settings

Configure the plugin via environment variables:

| SETTING | DEFAULT | DESCRIPTION |
| :- | :- | :- |
| `api_key` | `none` | Authenticates requests to the PiyAPI engine. |
| `user_id` | `none` | Identifies the memory owner. |
| `top_k` | `5` | Maximum number of memories returned per search. |
| `max_content_chars` | `4000` | Maximum characters captured per memory block. |
| `search_scope` | `repo` | Default scope used for retrieval. |
| `telemetry` | `true` | Enables anonymous usage telemetry. |

```bash theme={null}
export PIYAPI_API_KEY="..."
export PIYAPI_USER_ID="..."
export PIYAPI_SEARCH_SCOPE="repo"
```

## Upgrading

Before upgrading to a new plugin version, verify the following checklist to avoid breaking your existing configuration or memory behavior:

* Review changed configuration keys
* Check command deprecations/changes
* Verify memory compatibility
* Re-run plugin setup
* Confirm agent compatibility

## Troubleshooting

| PROBLEM | RESOLUTION |
| :- | :- |
| **Missing API key** | Export the `PIYAPI_API_KEY` and restart the plugin. |
| **Unauthorized** | Verify the API key and account permissions via `GET /api/v1/verify`. |
| **No memory after session** | Ensure memory capture is enabled and the plugin successfully flushed the session. |
| **Plugin won't start** | Verify your agent version is supported and the plugin installation succeeded. |
| **Search returns nothing** | Check the active search scope and verify memories exist within that boundary. |

## Telemetry

**What may be collected:**

* Event type
* Plugin version
* Runtime information
* Basic performance and error metadata

<Note>
  Document the exact telemetry behavior here before production release.
</Note>

```bash theme={null}
export PIYAPI_TELEMETRY=false
```

## Related Agent Plugins

<CardGroup cols={2}>
  <Card title="PiyAPI MCP" icon="plug">
    Connect PiyAPI memory through MCP-compatible workflows.
  </Card>

  <Card title="Codex Integration" icon="code">
    Add persistent context to supported Codex workflows.
  </Card>

  <Card title="Cursor" icon="cursor">
    Persistent memory for Cursor.
  </Card>

  <Card title="OpenCode" icon="terminal">
    Context-aware OpenCode workflows.
  </Card>

  <Card title="Gemini CLI" icon="sparkles">
    Memory for Gemini CLI agents.
  </Card>

  <Card title="Cline" icon="bot">
    Persistent context for Cline.
  </Card>
</CardGroup>

<Tip>
  **Building with PiyAPI?** Explore the open-source stack, contribute integrations, or browse the developer community.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.