Getting Started

Install phren, create your first project, and start building persistent memory for your AI agents.

Installation #

Five steps from zero to working memory.

npm install -g @phren/cli

phren init

phren init
  Detected agents: Claude Code, Copilot
  Created ~/.phren/
  Registered MCP server in ~/.claude/settings.json
  Registered hooks: SessionStart, UserPromptSubmit, PostToolUse, Stop
  Wrote Copilot MCP config
  Initialized git repo in ~/.phren
  Done. Run 'phren verify' to check setup.

# From inside your project directory
phren add

# Or specify a path
phren add ~/my-project

phren verify

phren verify
  Root: ~/.phren (shared mode)
  Profile: main (3 projects)
  Hooks: Claude Code (SessionStart, UserPromptSubmit, PostToolUse, Stop)
  MCP: registered in ~/.claude/settings.json
  Git: clean, remote configured
  All checks passed.

Quickstart #

The fastest path from zero to working memory. It combines the steps above:

phren quickstart

This runs phren init followed by an interactive project scaffolding wizard.

How It Works #

phren operates on three paths during every prompt cycle:

1. Retrieval: keyword extraction from your prompt, synonym expansion, FTS5 search, and snippet injection into agent context.
2. Governance: citation validity checks, confidence decay, policy thresholds to filter low-quality memories.
3. Persistence: MCP tools write findings/tasks, the Stop hook auto-commits and pushes to git.

Hooks run at lifecycle points:

• SessionStart: git pull on ~/.phren, project context injection
• UserPromptSubmit: search + inject relevant context on every prompt
• PostToolUse: queue review candidates and capture follow-up context after tool calls
• Stop: auto-commit and push after every response

First-Run Lifecycle

flowchart LR
    A["npm install -g
@phren/cli"] --> B["phren init"]
    B --> C["Hooks wired"]
    C --> D["First prompt"]
    D --> E["SessionStart hook
git pull"]
    E --> F["UserPromptSubmit hook
FTS5 search"]
    F --> G["Context injected
into agent"]
    G --> H["Stop hook
git commit + push"]

    style A fill:#1a1a3e,stroke:#00E5FF,color:#E8E4D9
    style B fill:#1a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style C fill:#1a1a3e,stroke:#28C840,color:#E8E4D9
    style D fill:#1a1a3e,stroke:#00E5FF,color:#E8E4D9
    style E fill:#1a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style F fill:#1a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style G fill:#1a1a3e,stroke:#28C840,color:#E8E4D9
    style H fill:#1a1a3e,stroke:#FFBD2E,color:#E8E4D9
        

Multi-Repo Setup #

Add as many projects as you want. Each gets its own findings, tasks, and config:

phren add ~/frontend-app
phren add ~/backend-api
phren add ~/shared-lib

Each project has an ownership mode that decides who owns its instruction files. Set it with phren add --ownership <mode>, or change the default with phren config project-ownership <mode>. See Project Ownership.

Profiles & Machines #

Profiles map sets of projects to machine roles:

# ~/.phren/profiles/work.yaml
projects:
  - frontend-app
  - backend-api
  - shared-lib

# ~/.phren/profiles/personal.yaml
projects:
  - side-project
  - dotfiles

Map machines to profiles in ~/.phren/machines.yaml:

machines:
  work-laptop: work
  home-desktop: personal
  server: work

Syncing Across Machines #

~/.phren is a git repo. Sync across machines:

# On a new machine
git clone <your-store-remote> ~/.phren
phren profile switch work   # map this machine to a profile
phren init -y               # wire MCP, hooks, and project links

# Pull the latest on any machine
phren store sync

The Stop hook commits and pushes your changes after each response. The SessionStart hook automatically runs git pull at the start of every session. Periodic checks are off by default; enable checks every minute with phren config pull-interval 60 while an MCP server is running.

Agent Setup #

phren init auto-configures all detected agents:

• Claude Code: MCP server + hooks for SessionStart, UserPromptSubmit, PostToolUse, Stop
• Copilot: MCP server config for chat mode
• Cursor: MCP settings for agent/composer mode
• Codex: MCP server registration

Verify with phren doctor --agents.

Troubleshooting #

Node.js Version Mismatch

phren requires Node.js 22.19+. If you see syntax errors:

node --version   # must be v22.19.0 or later
nvm use 20       # if using nvm

Permission Errors

If npm install -g fails with EACCES:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.npm-global/bin:$PATH"

MCP Connection Failures

If your agent cannot connect to the phren MCP server:

# Quick fix: re-run init to regenerate MCP config
phren init

# Or run doctor with auto-fix
phren doctor --fix

Hooks Not Firing

# View hook status
phren hooks list

# Check for errors
phren hooks errors --limit 5

Phone App and Phren Hook

Read your memory and talk to your running agents from your phone. Nothing goes through a phren server.

phren for iPhone and Android #

The app shows findings, notes, tasks, and the review queue from your store, and lets you chat with the agent sessions on your computers. The iPhone app is in TestFlight testing and the Android app is in early testing; neither is in a store yet. Get started walks through setup step by step. Phren apps shows each app with screenshots. The iPhone and Android pages cover each app, and the privacy policy covers both.

It needs:

• Phren Hook on each computer that runs your agents. npx --yes @phren/cli@latest pair installs it and pairs the phone.
• Herdr on that computer for chat, status, approvals and starting agents. Without it you get memory and an SSH terminal that ends when the connection drops.
• SSH to each computer, and Tailscale when you are away from home. No public port is needed.
• Your store, read from a paired computer or synced through GitHub. Support lists the GitHub token permissions.

Phren Hook #

Phren Hook is a local helper that connects your phone to the agents on a computer. It needs macOS or Linux, Node.js 22.19+, Herdr, SSH, and lsof. Install it as the user who runs your agents:

npx --yes @phren/cli@0.3.56 bridge install
npx --yes @phren/cli@0.3.56 bridge doctor

Then open Agents → Add computer in the app and follow the steps. The Phren Hook page covers setup, updates, and troubleshooting.

Concepts

The building blocks of how phren stores, ages, and surfaces project knowledge.

Findings #

A finding is a single unit of knowledge stored in FINDINGS.md. Each one carries a type tag, a lifecycle state, and a confidence score that decays over time.

Finding Types

Phren recognizes six finding types. decision, pattern, pitfall, and bug can be set explicitly (the findingType param, or a manual [tag] prefix); workaround and context are written only by phren's own auto-tagging, but decay and search filtering treat all six the same way.

[decision] never decays. [bug] and [context] expire fastest (30 days); [workaround] next (60 days); [pattern] and [pitfall] last longest (365 days).

Citations: Findings can carry optional citations linking them to source code. Findings with valid citations rank higher; findings with missing citations receive a 0.8x penalty.

Lifecycle States

Every finding moves through a lifecycle that sets its retrieval ranking. A stale finding becomes active again when it is confirmed.

stateDiagram-v2
    [*] --> Active : add_finding
    Active --> Superseded : supersede
    Active --> Contradicted : conflict confirmed
    Active --> Retracted : retract
    Active --> Stale : decay
    Stale --> Active
    Stale --> Pruned : maintain prune
    Superseded --> Pruned : maintain prune
    Retracted --> Pruned : maintain prune
    Active --> InvalidCitation : bad citation
        

Trust & Decay #

Every finding starts with full confidence (1.0). As it ages, confidence falls in a straight line between these points. The defaults come from the retention policy; change them with phren config policy.

A finding below 0.35 confidence (minInjectConfidence) is left out of injected context.

Findings repeatedly confirmed accumulate a decay-resistance boost and decay 3x slower. Pin permanent knowledge to truths.md with revise_finding (action pin) or phren pin.

Consolidation #

As FINDINGS.md grows, phren triggers consolidation. It deduplicates entries, archives older ones into collapsed <details> blocks, and promotes patterns appearing in 2+ projects to global/FINDINGS.md.

Automatic triggers:

• 25 entries added since the last consolidation marker, or
• 60 days have passed with at least 10 entries.

phren maintain consolidate my-app
phren maintain consolidate my-app --dry-run  # preview

Fragment Knowledge Graph #

A fragment is a named concept that links across findings and docs. Fragments let you trace a topic across projects.

graph LR
    subgraph "Project A"
      F1["[pitfall] Auth runs
before rate limiting"]
      F2["[decision] Use Zod
for validation"]
    end

    subgraph "Project B"
      F3["[pattern] JWT refresh
token rotation"]
    end

    subgraph "Fragments"
      FR1(("auth-flow"))
      FR2(("input-validation"))
    end

    F1 -->|mentions| FR1
    F3 -->|implements| FR1
    F2 -->|mentions| FR2

    style FR1 fill:#2a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style FR2 fill:#2a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style F1 fill:#1a1a3e,stroke:#FF8A90,color:#E8E4D9
    style F2 fill:#1a1a3e,stroke:#00E5FF,color:#E8E4D9
    style F3 fill:#1a1a3e,stroke:#00E5FF,color:#E8E4D9
        

Use cross_project_fragments() to find fragments that span several projects. These often point to shared dependencies or repeated pitfalls.

Session Continuity #

Sessions track continuity across agent restarts. When a session starts, phren provides the prior summary, recent findings, the active task, and pending review items.

sequenceDiagram
    participant Agent
    participant Phren
    participant Files as ~/.phren

    Agent->>Phren: session(action: start, project: my-app)
    Phren->>Files: Read last session summary
    Phren->>Files: Read recent findings
    Phren->>Files: Read task checkpoints
    Phren-->>Agent: Summary + findings + active task + hints

    Note over Agent,Phren: Agent works...

    Agent->>Phren: add_finding(...)
    Agent->>Phren: manage_task(action: complete)

    Agent->>Phren: session(action: end, summary)
    Phren->>Files: Write session summary
    Phren->>Files: Save task checkpoints
        

Task Checkpoints

Checkpoints record the state of in-progress work so an agent can pick up where the last one stopped. Each captures the task ID, edited files, failing tests, and next-step hints. Stored in .sessions/ and cleared on task completion.

Configuration

Environment variables, governance files, retention policy, workflow gates, proactivity, hooks, and feature flags.

Environment Variables #

phren reads environment variables for runtime behavior. Set them in your shell profile or ~/.phren/.env.

Core

Semantic / Embedding

Feature Flags

Governance Files #

Policy is configured via JSON files in ~/.phren/.config/. Use phren config subcommands to read and write these safely.

phren config policy get
phren config policy set memoryTTLDays=90 decayMultiplier=0.8
phren config workflow set taskMode=auto findingSensitivity=high

Hook Configuration #

Four built-in hooks fire automatically for Claude Code:

Manage hooks:

phren hooks list
phren hooks enable claude
phren hooks disable codex
phren hooks add-custom Stop "curl -s http://localhost:9090/notify"

Proactivity #

Controls how aggressively phren captures findings and tasks:

phren config workflow set proactivity=medium

CLI Reference

All phren CLI commands, organized by category. Run phren --help for a quick summary.

General #

Search #

$ phren search "authentication middleware"
  [my-app] [pitfall] Auth middleware runs before rate limiting (0.92)
  [backend] [decision] Use passport.js for all auth flows (0.87)

Tasks #

Findings #

Projects #

Skills #

Hooks #

Config #

Teams & Stores #

Notes #

Daily notes are lightweight. They are searchable but not injected into context until you promote one to a finding.

Code Index #

Needs the code module: phren modules enable code.

Coding agent #

phren's own coding agent, shipped as the @phren/agent package (npm install -g @phren/agent). It starts every session with the project's memory loaded and runs on a ChatGPT/Codex subscription, OpenAI, OpenRouter, Anthropic or local Ollama models. The agent guide covers providers, MCP servers, permissions and headless runs.

Schedules #

Scheduled prompts run through Phren Hook on the computer you assign. Needs the schedules module.

phren owner-inbox list|add|resolve collects owner work. phren conductor integrator --session <id> [--computer <name>] chooses who receives structured PR reports. Workers use phren dispatch report --prs <JSON> before ending their turn.

Dispatch #

Send work to agents on your enrolled computers through Phren Hook. Needs the conductor module.

Modules & Presets #

Modules turn features on per store or profile. Disabling one keeps its data.

Maintenance #

MCP Tools

The phren MCP server has 77 tools. By default an agent sees 10 of them. Every tool returns { ok, message, data?, error? }.

Tool Profiles #

The server exposes one of two profiles. Switch with phren config mcp-profile core or phren config mcp-profile full, or set PHREN_MCP_PROFILE.

Core Tools

The groups below list the full profile's tools. In core, call them through the composite named above or through phren_admin.

Search & Browse 10 tools #

Daily Notes 5 tools #

Lightweight daily Markdown notes are explicitly searchable but are not automatically injected or included in finding lifecycle and graph processing.

Task Management 7 tools #

Finding Capture 9 tools #

Memory Quality 3 tools #

Data Management 4 tools #

Fragment Graph 5 tools #

Session Management 4 tools #

Skills Management 5 tools #

Hooks Management 4 tools #

Configuration 2 tools #

Store Management 1 tool #

Topic Summaries 2 tools #

Code Index 5 tools #

Needs the code module and an index built with phren code index.

Dispatch 9 tools #

Needs the conductor module and a running Phren Hook.

Return Format #

{
  "ok": true,
  "message": "Found 3 results",
  "data": { ... }
}

// On error:
{
  "ok": false,
  "error": "Project not found: foo"
}

Maintenance commands (phren maintain) are CLI-only and not exposed over MCP.

Skills Guide

Reusable instructions that agents invoke as slash commands. Write once, use everywhere.

What Are Skills #

A skill is a markdown file with YAML frontmatter that defines a reusable procedure. Type /skill-name in an agent session and the agent reads the skill file and follows its instructions.

• Portable: skills live in ~/.phren and sync via git
• Scoped: global skills apply everywhere; project skills override globals
• Versioned: full git history and rollback
• Agent-agnostic: any agent with MCP access can execute skills

Anatomy of a Skill #

---
name: deploy-staging
command: /deploy-staging
description: Deploy the current branch to staging
tags: [devops, deploy]
---

# Deploy to Staging

1. Run the test suite: `npm test`
2. Build the production bundle: `npm run build`
3. Deploy to staging: `./scripts/deploy.sh staging`
4. Verify the deployment at https://staging.example.com
5. Report the deployment status.

Frontmatter Format

Global vs Project Skills #

Project always wins. Global skills live in ~/.phren/global/skills/. Project skills live in ~/.phren/<project>/skills/.

Resolution Order #

1. Project skills: ~/.phren/<project>/skills/
2. Global skills: ~/.phren/global/skills/

If a project skill has the same name as a global skill, the project skill wins.

Built-in Skills #

Managing Skills #

phren skills list                            # List all
phren skills add my-project ./skill.md       # Add to project
phren skills show deploy --project my-project # View content
phren skills resolve my-project               # Print manifest
phren skills doctor my-project                # Diagnose visibility
phren skills enable my-project deploy         # Re-enable
phren skills disable my-project deploy        # Disable
phren skills remove my-project deploy         # Delete

Interactive Shell

A terminal UI for browsing and managing your entire project store. Launch with phren or phren shell.

Views #

The shell has eight views. Switch between them with single-key shortcuts or the : palette.

Projects p

Tasks b

Findings l

Review Queue m

Skills s

Hooks k

Health h

Keybindings #

Palette Commands #

State Persistence #

The shell saves state to .runtime/shell-state.json: selected project, active filter, page, and rows per page. Use :reset to clear.

VS Code Extension

Browse, search, and manage phren knowledge directly from VS Code.

Overview #

• Activity bar tree view of projects, findings, tasks, skills, hooks, sessions
• Full-text search via quick pick (Ctrl+Shift+K)
• Interactive fragment graph webview
• Inline finding capture from editor selections
• Task management from the tree view
• Session overview panels

Installation #

npm install -g @phren/cli
phren init

# From marketplace
ext install alaarab.phren-vscode

# Or build from source, in a clone of the phren repo
pnpm install
pnpm --filter phren-vscode run compile

Tree View #

The activity bar icon opens a hierarchical view: Projects, Findings, Tasks, Skills, Hooks, Sessions, and Review Queue. Title bar buttons provide Search, Graph, Refresh, and Sync.

Search #

Press Ctrl+Shift+K to search across all indexed content. Also available from the command palette: Phren: Search Knowledge.

Findings #

Capture findings from editor selections (right-click), the command palette, or the tree view. Right-click findings for lifecycle actions: remove, supersede, retract, resolve contradictions.

Tasks #

Add, complete, update, pin, and remove tasks from the tree view. Right-click for GitHub integration: link issues or create new ones from tasks.

Settings #

All Commands #

All commands accessible via Ctrl+Shift+P by typing "Phren":

Architecture

Data flow, retrieval pipeline, governance, persistence, hook lifecycle, and MCP integration.

System Overview #

phren operates on three paths during every prompt cycle:

1. Retrieval: keyword extraction, synonym expansion, FTS5 search, snippet injection
2. Governance: citation validity, confidence decay, policy thresholds
3. Persistence: MCP writes + Stop hook git commit/push

flowchart TB
    subgraph "Agent Session"
        A["User Prompt"] --> B["SessionStart Hook"]
        B --> C["git pull ~/.phren"]
        C --> D["UserPromptSubmit Hook"]
        D --> E["Keyword Extraction"]
        E --> F["FTS5 Search + Synonyms"]
        F --> G["Trust Scoring"]
        G --> H["Context Injection"]
    end

    subgraph "MCP Tools"
        I["add_finding"] --> J["~/.phren/project/FINDINGS.md"]
        K["add_task"] --> L["~/.phren/project/tasks.md"]
        M["search_knowledge"] --> N["FTS5 Index"]
    end

    subgraph "Persistence"
        O["Stop Hook"] --> P["git add + commit"]
        P --> Q["git push"]
    end

    H --> I
    H --> K
    H --> M
    J --> O
    L --> O

    style A fill:#1a1a3e,stroke:#00E5FF,color:#E8E4D9
    style D fill:#1a1a3e,stroke:#9B8DC8,color:#E8E4D9
    style H fill:#1a1a3e,stroke:#28C840,color:#E8E4D9
    style O fill:#1a1a3e,stroke:#FFBD2E,color:#E8E4D9
        

Retrieval Pipeline #

On every UserPromptSubmit, phren extracts keywords from the user's prompt, expands them with learned synonyms, and runs an FTS5 query across all indexed content. Results are trust-scored, filtered by confidence thresholds, and injected into the agent's context window within the configured token budget.

Search ranking factors

• FTS5 relevance score (BM25)
• Age-based confidence decay
• Citation validity (valid = boost, missing = 0.8x penalty)
• Finding lifecycle state (active = 1.0x, superseded = 0.25x, retracted = 0.1x)
• Low-value pattern filtering
• Git context boost (when enabled)

Governance #

Governance ensures memory quality through policy-driven checks:

• Retention policy: TTLs, decay multipliers, prune thresholds
• Workflow policy: approval gates for risky operations, finding sensitivity
• Access control: RBAC via PHREN_ACTOR and access-control files
• Audit log: all mutations logged to .runtime/audit.log

Hook Lifecycle #

sequenceDiagram
    participant Agent
    participant Hooks
    participant Phren as ~/.phren
    participant Git

    Agent->>Hooks: SessionStart
    Hooks->>Git: git pull
    Hooks->>Agent: Project context

    Agent->>Hooks: UserPromptSubmit (every prompt)
    Hooks->>Phren: Extract keywords
    Hooks->>Phren: FTS5 search
    Hooks->>Agent: Inject context (token-budgeted)

    Note over Agent: Agent responds, calls MCP tools

    Agent->>Hooks: Stop (after every response)
    Hooks->>Git: git add + commit + push
        

Directory Structure #

FTS5 Indexing #

phren builds an in-memory FTS5 index on startup from all markdown files in the store. Key behaviors:

• @import shared/file.md resolves to global/ dir, with cycle detection and depth cap
• reference/ subdirectories classified as reference type
• Task Done sections stripped to reduce noise
• Archived findings (inside <details> blocks) stripped from index
• Configurable include/exclude globs via phren config index

Key Patterns #

• Starter bundled in npm package, not a separate repo
• Path traversal prevention via isValidProjectName + safeProjectPath
• Init is idempotent: re-running updates MCP + hooks without clobbering data
• Node resolved-path in hooks (not npx) avoids cold-start timeout
• Hook detection uses path segments (not substring) to avoid false positives
• Stop hook fires after every response including subagents
• File locking prevents concurrent writes to FINDINGS.md and tasks.md

Contributing

How to set up, build, test, and submit changes to phren.

Dev Setup #

Clone, build, and test in under a minute.

git clone https://github.com/alaarab/phren.git
cd phren
pnpm install
pnpm build
pnpm test

The repo is a pnpm workspace built with turborepo. pnpm build compiles every package; the CLI builds from packages/cli/src/ into packages/cli/dist/.

Prerequisites

• Node.js 22.19+
• pnpm 10 (the version is pinned in package.json; corepack enable picks it up)

Project Structure #

Key files and what they do.

Testing #

Running the test suite and filtering by pattern.

pnpm test                                  # run all tests
pnpm test -t "pattern"                     # filter by test name
pnpm test packages/cli/src/utils           # run matching files
pnpm exec vitest                           # watch mode

Run tests from the repo root. Test files sit next to their source as *.test.ts. Add tests for a new feature in the same directory.

Code Style #

Read AGENTS.md for the full set of conventions. The highlights:

Making Changes #

1. Create a feature branch from main
2. Make your changes with tests
3. Run pnpm build && pnpm test && pnpm lint and make sure everything passes
4. Keep commits focused: one logical change per commit
5. Write commit messages that explain why, not just what

Pull Requests #

Keep PRs small and focused. One feature or fix per PR.

• Include a short description of what changed and why
• If your PR changes user-facing behavior, update the README
• If your PR adds or changes MCP tools, update docs/api-reference.md, docs/llms-install.md, and docs/llms-full.txt
• If your PR changes finding lifecycle, session checkpoints, web-ui security, RBAC, or telemetry, update the matching docs in the same PR
• Make sure CI passes before requesting review

Commit Conventions

Use conventional commits.

feat: add synonym expansion for search queries
fix: FTS5 sanitizer stripping valid URLs
docs: update API reference with bulk tools
test: add coverage for session checkpoint edge cases
refactor: extract keyword logic from hook-prompt

Prefixes: feat:, fix:, docs:, test:, refactor:

Adding a New MCP Tool #

Five steps to ship a new tool.

1. Add the tool definition in the matching module (packages/cli/src/tools/<domain>.ts) following the existing server.registerTool() pattern
2. Implement the handler: call data-access functions, return { ok, message, data }
3. Import a new module from packages/cli/src/index.ts. A tool outside the core list is reachable in the core profile through phren_admin.
4. Add tests in the relevant *.test.ts file
5. Update docs: docs/api-reference.md, docs/llms-install.md, docs/llms-full.txt, and integration/security/governance docs when behavior affects hooks, skills, RBAC, web UI, or telemetry

Adding a Global Skill

1. Create packages/cli/starter/global/skills/your-skill/SKILL.md
2. Follow the existing skills: frontmatter with name and description, then the steps
3. Test locally by running phren init and invoking /your-skill in a Claude Code session

Reporting Bugs

Open an issue with:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Your Node.js version and OS

Security

Phren is local-first. Your data never leaves your machine unless you push it.

Data Storage #

Phren stores all state as local files under ~/.phren (shared mode) or <repo>/.phren (project-local mode). The data is:

• Plain text: markdown files for findings, tasks, summaries, and skills
• Structured JSON: governance policies, session data, runtime state
• Git-backed: changes are committed locally and optionally pushed to a remote you control

Credential Handling

Phren reads credentials exclusively from environment variables. It never writes secrets to disk.

Secret Scanning

The finding quality filter rejects entries that match common secret patterns:

• API keys and tokens (common prefixes like sk-, ghp_, Bearer)
• Connection strings with embedded credentials
• PII patterns (emails, phone numbers in certain formats)

Access Control #

RBAC and authentication for shared environments and the web UI.

Role-Based Access Control

Identity is resolved from PHREN_ACTOR (in trusted/test contexts) or the OS user identity.

All write, policy, and delete operations are checked against RBAC before mutation. Unauthorized attempts are logged in .runtime/audit.log.

Web UI Security

The memory web UI (phren web-ui) applies layered security:

• Loopback binding: listens only on 127.0.0.1, not on network interfaces
• Auth token: random per-run token required for all requests
• CSRF protection: mutating routes require a single-use CSRF token with TTL
• Security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff

Network Activity #

Phren makes no network calls by default. All external calls are opt-in.

Auto-Extract Privacy

When PHREN_FEATURE_AUTO_EXTRACT is enabled, phren extracts insights from project context on each prompt. The extraction:

• Runs entirely locally using the configured model
• Respects a per-session cooldown (PHREN_AUTOCAPTURE_COOLDOWN_MS, default 30s)
• Caps findings per session (PHREN_AUTOCAPTURE_SESSION_CAP, default 10)
• Applies the same quality filter that rejects secrets and PII
• Tags extracted findings with source: extract provenance for auditability

Telemetry

Opt-in, local-only usage tracking. Disabled by default. Enable with phren config telemetry on. Data is stored in .runtime/telemetry.json and never sent anywhere.

Reporting a Vulnerability #

If you find a security issue, report it privately. Do not open a public issue.

Include: a description of the vulnerability, steps to reproduce, the impact, and your suggested fix.

What Counts as a Security Issue

• Path traversal: reading or writing files outside the phren directory
• Arbitrary code execution through MCP tool inputs
• Information disclosure: leaking data from other projects or profiles
• Injection attacks through FTS5 queries or CLI arguments
• Bypass of memory access controls or role-based permissions

Response Timeline

Security fixes are applied to the latest release only. We follow coordinated disclosure and credit reporters in the changelog unless they prefer anonymity.

Frequently Asked Questions

Common questions about phren, answered.

How is this different from just using AGENTS.md? #

AGENTS.md loads the entire file on every prompt. If your file is 2,000 tokens, you pay 2,000 tokens every single time, whether the content is relevant or not. With five agents running in parallel, that is 10,000 tokens of context before anyone types a word.

Phren searches what you wrote and injects only what matches the current prompt. By default it targets roughly 550 tokens with PHREN_CONTEXT_TOKEN_BUDGET, regardless of how large your knowledge base grows.

AGENTS.md is also static. Phren learns as you work. Every bug traced, every decision made, every pattern discovered gets saved automatically. The next session starts with that knowledge already in context.

Does this slow down my prompts? #

Usually not on a warm local repo. The hook runs locally: keyword extraction, FTS5 search, and context injection all happen against a local SQLite index with no network calls in the default path.

The main exceptions are the first prompt in a session (where SessionStart pulls the repo from git) and very large or slow filesystems. On a fast connection the pull is often under a second.

What happens when I run multiple agents at the same time? #

They all read and write the same ~/.phren directory. Concurrent reads are safe. Writes are serialized within a process by file locks; cross-process synchronization happens at the git layer.

In practice: an agent on Codex hits a pitfall and saves a finding. On the next git pull cycle, a Claude Code session on a different machine has it in context. No coordination code, no message passing, just a shared git repo.

What failure modes should I expect? #

• No remote configured: auto-save still commits locally, but nothing syncs across machines until you add a remote.
• Push failed: the commit stays local and phren records the error so phren status can show it.
• Hooks disabled or stale: retrieval stops, but your files are still there; rerun phren init.
• Stale index: search quality drops until the next rebuild; phren doctor will flag index trouble.
• Governance lockout: if access control blocks a write, nothing is silently discarded; check .config/access-control.json.

How does trust decay work? #

Every finding has a confidence score that falls as it ages: 1.00 for the first 30 days, then 0.85 at 60 days, 0.65 at 90, and 0.45 at 120. An uncited finding scores 0.8x. Trust & Decay has the full table.

Entries below 0.35 are left out of injected context. You can pin a truth with phren pin or revise_finding (action pin) to make it never decay.

What gets saved automatically vs manually? #

Automatic

• Findings added via add_finding MCP tool
• Task items via add_task
• Session state committed and pushed by the Stop hook after every response

Manual

• Running /phren-consolidate when findings pile up
• Running phren maintain govern to queue low-value entries for review
• Pinning findings that should never decay

How do I add a new project? #

cd ~/code/my-project
phren add

Phren bootstraps ~/.phren/my-project/ and adds it to your active profile. For a brand-new scaffold: /phren-init my-project

Does phren require MCP? #

No. MCP is recommended because it lets the agent save findings and tasks. Without it, phren runs in hooks-only mode and the prompt hook still injects context.

phren init --mcp off    # Install without MCP
phren mcp-mode on       # Toggle anytime

Which agents are supported? #

Claude Code, GitHub Copilot CLI, Cursor, VS Code Copilot, and OpenAI Codex. Claude gets full native lifecycle hooks plus MCP. The others get generated hook configs plus session wrappers.

Platforms #

Linux is the primary validation path. macOS and Windows are supported, with explicit config-path handling for their user-home layouts.

Web UI #

phren web-ui

Opens a browser-based interface at localhost:3499. The review queue is read-only there. Filter by machine, model, and project. Loopback-only bind, random per-run auth token, CSRF protection, and CSP headers.

Telemetry #

No, telemetry is not on by default. It is opt-in and local-only. phren config telemetry on

Uninstall #

phren uninstall removes the active install. Shared mode removes config, hooks, and the active phren root. Project-local mode removes <repo>/.phren and workspace MCP entry. Export or back up before uninstalling.

Sharing & Teams

Sync phren knowledge across machines, manage access with RBAC, and collaborate across projects.

Profiles #

A profile defines which projects a machine should have access to. Profiles live as YAML files in ~/.phren/profiles/.

# ~/.phren/profiles/work.yaml
name: work
projects:
  - global
  - web-app
  - api-server
  - shared-lib

Each profile lists the project directories that should be synced and linked. The global entry is special: it contains skills and config that apply everywhere.

phren config profiles       # list profiles and their projects
phren profile switch work   # map this machine to the work profile

To change a profile's projects, run these in the interactive shell's : palette, or use the /phren-profiles skill:

:profile add-project work my-new-project
:profile remove-project work old-project

Machines #

The machines.yaml file maps hostnames to profiles. When phren init runs on a new machine, it reads the current hostname, applies the mapped profile, and refreshes local integration config.

# ~/.phren/machines.yaml
work-desktop: work
home-laptop: personal
ci-server: minimal

Syncing via Git #

Editing memory on two computers at once? See Sync conflicts across computers for the rules and steps to fix a conflict.

The ~/.phren directory is a git repository. Syncing is plain git, automated through hooks:

• The SessionStart hook runs git pull on ~/.phren at the beginning of every session
• The Stop hook auto-commits and pushes ~/.phren changes after every response

Findings, tasks, and skills sync automatically as you work. Use profiles plus machines.yaml to scope which projects are active on each machine, then run phren init after profile changes to refresh local config.

Phren Hook syncs stores every five minutes by default, even without an active agent session. Separate periodic remote checks while an MCP server runs are off by default. Clients sharing a store coordinate one check per interval. These checks save pending local edits before pulling and can combine changes from both computers. A conflict phren cannot resolve cancels the attempted combination and names the files. Checks wait if another Git operation is running. Failed remote checks back off, up to 30 minutes or the configured interval if longer.

phren config pull-interval       # show this machine's effective setting
phren config pull-interval 60    # enable checks every minute
phren config pull-interval 600   # every ten minutes
phren config pull-interval off   # disable periodic checks (default)

The setting is machine-local, accepts whole seconds from 30 to 86400 (or 0/off), and is reloaded by running servers. PHREN_PULL_INTERVAL_SECONDS overrides it. Pulled changes refresh each client's memory index and existing managed skill/instruction mirrors; agents consume instructions at their normal reload boundaries. No service is installed: periodic checks stop when the MCP server closes. The manual preset and project-local/workspace-Git installs do not poll by default. SessionStart and Stop hooks are configured separately.

Machine Setup

phren init wires everything together on a machine. It detects the current install mode, configures MCP settings for supported agents, registers lifecycle hooks, applies machine/profile defaults, and refreshes generated assets.

Consolidation #

As findings accumulate, phren detects when they need consolidation. Thresholds: 25 entries since last consolidation marker, or 60 days + 10 entries. Consolidation archives old entries, deduplicates, and promotes patterns that appear in 2+ projects to global scope.

phren consolidation-status
phren maintain consolidate my-project

Fragment Graph

Fragments are named concepts that connect findings across projects. Use cross_project_fragments to find fragments shared across multiple projects.

phren graph
phren graph link web-app "Turbo builds avoid dist races" "build-system"

Cross-Project Search

The search_knowledge MCP tool searches across all indexed projects by default. Cross-project findings from global/FINDINGS.md are included in all searches.

RBAC Roles #

Phren supports four role levels. The actor is identified by PHREN_ACTOR (defaults to $USER).

Access control is configured in ~/.phren/.config/access-control.json. If no file exists, all users have full access.

Audit Log

All mutations are recorded in ~/.phren/.runtime/audit.log. Each entry includes the actor, action, timestamp, and relevant parameters.

Team Workflows #

For teams sharing a phren repository:

1. Create a shared git remote for ~/.phren
2. Define profiles per team role (e.g. frontend.yaml, backend.yaml)
3. Register each machine in machines.yaml, then run phren init
4. Set up RBAC so team leads are admins, developers are maintainers or contributors

Example: Two-Person Team

# Alice's laptop
phren init              # machine: alice-mbp, profile: fullstack

# Bob's desktop
git clone <phren-remote> ~/.phren
phren init              # machine: bob-desktop, profile: fullstack

# Both work independently; Stop hook syncs after each response
# Weekly: run /phren-consolidate to merge insights

Team Stores #

A team store is a shared git repository structured like a phren store. Each team member clones it locally, and phren routes reads and writes automatically based on project claims in the store registry.

How It Works

Phren maintains a store registry at ~/.phren/stores.yaml that lists every store the user has access to. Each store has a role:

CLI Commands

Write Routing

When you add a finding or task, phren resolves which store receives the write:

1. If store-qualified (e.g. forge-team/forge), use the explicit store
2. If a team store claims the project in its registry, route to that store
3. Otherwise, use the primary (personal) store

# Finding goes to forge-team store (project claimed)
phren add-finding forge "Always validate JWT expiry"

# Explicit store target
phren add-finding forge-team/forge "Always validate JWT expiry"

# Unclaimed project → personal store
phren add-finding my-side-project "Use pnpm for this one"

Git Sync

Sync happens automatically at session boundaries:

• Session start: git pull on all stores (team, readonly, primary)
• Stop hook: for each writable store, git add + commit + push

Team stores use an append-only journal format (journal/YYYY-MM-DD-actor.md) to avoid merge conflicts. Each team member writes to their own file, so concurrent pushes merge cleanly.

Example: Setting Up a Team

# Alice creates the team store
phren team init forge-team --remote git@github.com:example-org/phren-forge.git
phren team add-project forge-team forge
phren team add-project forge-team forge-api

# Bob joins
phren team join git@github.com:example-org/phren-forge.git

# Both now share findings for forge and forge-api
# Personal findings for other projects stay in ~/.phren

Project Ownership