phren init creates your project store with starter templates. Each project gets its own directory. Tell phren more as the project grows.

Shared mode uses one phren repo that carries your project memory. Push it to a private remote, clone it anywhere you work.

cd ~/.phren
git init && git add . && git commit -m "Initial phren"
git remote add origin git@github.com:YOU/my-phren.git
git push -u origin main

On a new machine: run phren init and paste your repo URL when the walkthrough asks if you have an existing phren repo.

SessionStart pulls on open. The Stop hook commits locally after each response and queues a best-effort push when a remote exists. This is eventual consistency -- git gives you portability and auditability, not real-time sync.

Shared state lives in your phren repo. Generated local state does not. The .claude/ mirrors created inside app repos, tool-specific instruction files such as .github/copilot-instructions.md, and the local machine alias file (~/.phren/.machine-id) are machine-local artifacts and should not be treated as canonical project memory.

machines.yaml maps each hostname to a profile:

work-desktop: work
home-laptop: personal

Each profile lists its projects:

# profiles/personal.yaml
name: personal
projects:
  - global
  - my-api
  - my-frontend
  - side-project

Profiles decide which projects are active on each machine. phren init is the normal refresh path: it registers the current machine/profile mapping, rewires supported agents, and offers to add the current repo when needed.

If you want stable names across laptops, desktops, and CI, set the machine name explicitly at onboarding instead of relying on the raw OS hostname:

phren init --machine work-laptop --profile work

For CI or unattended setup:

phren init --machine ci-runner --profile work

Project-local mode is the repo-owned install:

cd /path/to/repo
phren init --mode project-local

That creates:

• <repo>/.phren/phren.root.yaml
• <repo>/.phren/<project>/...
• <repo>/.vscode/mcp.json entry for the workspace server

Design constraints:

• one phren root per repo
• one primary project per project-local root
• no home-directory writes by default
• no global hooks
• VS Code workspace MCP is the supported editor integration in this mode

This mode is for repo-owned memory, not cross-machine personal memory. If you want profiles, machine mappings, shared hooks, and the full personal-memory workflow, use shared mode.

When more than one tool or session touches the same project, they all talk to the same phren. A Codex session hits a pitfall and tells him. Ten minutes later, a Claude Code session on a different machine gets that fragment in its context — phren carried it over on the next sync cycle. No coordination service or custom broker layer, just phren and a shared git repo.

• Parallel agents share findings on push/pull cycles
• Sequential sessions build on each other. Session 47 knows everything sessions 1 through 46 learned.
• Cross-project patterns surface when the same insight shows up in two or more projects
• Tasks persist across agents and sessions. One agent adds a task, another finishes it.

Because it's all markdown in git, you have a full record of what your agents learned, when, and which session produced each insight.

Core mode (default). Markdown is the source of truth. Git handles sync and audit history. Retrieval runs through a local SQLite FTS5 index. This is the simplest and most portable setup: no required hosted service, predictable token budgets, and a repo you can inspect with normal tools.

Optional semantic mode. Phren can also use Ollama or an embeddings API for gated semantic recovery when lexical retrieval comes up short. This is mainly for paraphrase-heavy or fuzzy queries. If you mostly search by filenames, symbols, commands, project names, or exact phrases, the lexical path is usually the important one and semantic mode may stay mostly dormant. Semantic mode helps phren find things when the words don't match exactly, not as a blanket speed claim.

Install modes

Shared mode is the default:

phren init

Project-local mode is explicit:

phren init --mode project-local

In project-local mode:

• phren mcp-mode on|off manages .vscode/mcp.json
• phren hooks-mode is unsupported
• phren config machines and phren config profiles are shared-mode only
• phren uninstall removes <repo>/.phren and the workspace MCP entry

Hooks-only mode (no MCP tools):

phren init --mcp off

Toggle anytime:

phren mcp-mode on       # shared: user MCP, project-local: VS Code workspace MCP
phren mcp-mode off      # disable MCP for the current install mode
phren hooks-mode off    # shared mode only
phren hooks-mode on     # shared mode only

Templates

phren init --template <name> scaffolds with a project-specific starter:

To add an existing repo, run phren add from that directory, or just open a session there and phren will suggest it. Phren auto-detects git repos and folders that already contain CLAUDE.md.

Adding projects

From a project directory:

cd ~/code/my-project
phren add --ownership repo-managed

Or just open a session in the project directory. Phren notices the unfamiliar repo and asks whether you want him to remember it. If yes, he'll ask whether he should manage repo-facing CLAUDE.md / AGENTS.md files or leave repo-owned files alone. If you say no, he'll point you to phren add for later.

For a brand-new scaffold inside Claude:

/phren-init my-project

• phren add is the supported path for existing repos.
• Change the default add behavior later with phren config project-ownership <mode>.
• Change task automation later with phren config workflow set --taskMode=<off|manual|suggest|auto>.
• Tune capture levels later with phren config proactivity.findings <high|medium|low> and phren config proactivity.tasks <high|medium|low>.
• Platform support and release expectations are documented in docs/platform-matrix.md.
• Best-effort vs fail-closed behavior is documented in docs/error-reporting.md.
• Package/update behavior is documented in docs/versioning.md.
• Task items stay local by default. GitHub issue linkage is optional, and promotion is one-way unless you explicitly act on the linked issue.

Four skills for the things that can't be automatic:

When to run these manually:

• /phren-discover -- Run after your first week on a new project, or when you feel like things are slipping through the cracks. It tells you what's missing, what's stale, and what's stuck.
• /phren-consolidate -- Run after a burst of work across multiple projects, or monthly. It finds patterns that repeat across projects and promotes them to global knowledge so every agent benefits.
• phren maintain govern -- Run when search results feel noisy or after a long break from a project. It queues low-value and stale entries for review.
• phren maintain consolidate -- Run when findings in a single project feel repetitive. It deduplicates bullets in FINDINGS.md. Use --dry-run first to preview.

Put personal workflow skills in ~/.phren/global/skills/. phren init and later refresh runs wire them into supported agents automatically.

Per-project agent config

Drop a phren.project.yaml in ~/.phren/<project>/ to control what gets injected for that project:

# Opt out of global skill injection for this project
skills: false

# Register extra MCP servers when this project is linked
mcpServers:
  my-tool:
    command: node
    args: [/path/to/server.js]
  my-api:
    command: /usr/local/bin/api-server
    env:
      API_KEY: "from-your-env"

phren init applies project MCP servers into your agent config under namespaced keys (phren__<project>__<name>) and cleans them up when the config changes.

The MCP server indexes your project store into a local SQLite FTS5 database and exposes 60 tools across 11 modules:

• Search and browse (5): get_memory_detail, search_knowledge, get_project_summary, list_projects, get_findings
• Task management (13): get_tasks, add_task, add_tasks, complete_task, complete_tasks, remove_task, update_task, link_task_issue, promote_task_to_issue, pin_task, work_next_task, promote_task, tidy_done_tasks
• Finding capture (9): add_finding, add_findings, supersede_finding, retract_finding, resolve_contradiction, get_contradictions, remove_finding, remove_findings, push_changes
• Memory quality (2): pin_memory, memory_feedback
• Data management (3): export_project, import_project, manage_project
• Fragment graph (5): search_fragments, get_related_docs, read_graph, link_findings, cross_project_fragments
• Session management (4): session_start, session_end, session_context, session_history
• Operations and review (8): add_project, get_consolidation_status, health_check, list_hook_errors, get_review_queue, approve_queue_item, reject_queue_item, edit_queue_item
• Skills management (6): list_skills, read_skill, write_skill, remove_skill, enable_skill, disable_skill
• Hooks management (4): list_hooks, toggle_hooks, add_custom_hook, remove_custom_hook
• Extraction (1): auto_extract_findings

For parameter schemas and examples, see docs/api-reference.md.

Governance, policy, and maintenance tools are CLI-only (see phren config and phren maintain).

phren in a terminal opens the shell. Seven views, single-key navigation:

Palette commands

Tasks: :add, :complete, :move, :reprioritize, :context, :work next, :tidy

Findings: :find add, :find remove

Review queue: :mq approve, :mq reject, :mq edit

Memory quality: :govern, :consolidate

Git: :undo, :diff, :conflicts

Infrastructure: :run fix, :relink, :rerun hooks, :update

Navigation: :open <project>, :search <query>, :reset

The shell works the same on every machine, for every agent.

For scripting, hooks, and quick lookups from the terminal:

phren                                   # interactive shell (TTY default)
phren search "rate limiting"            # FTS5 search with synonym expansion
phren add-finding <project> "..."       # tell phren something worth remembering
phren pin <project> "..."               # promote canonical memory
phren tasks [project]                 # cross-project task view
phren status                            # health, active project, stats
phren doctor [--fix]                    # health checks + optional self-heal
phren verify                            # check init completed correctly
phren web-ui [--port=3499]              # lightweight web UI in the browser
phren update [--refresh-starter]        # update package; optionally refresh starter globals too
phren uninstall                         # remove phren config, integrations, and installed data

phren add [path] [--ownership <mode>]     # add current directory (or path) as a project
phren projects list                        # list all projects
phren projects configure <name> --ownership=<mode>  # change a project's ownership mode
phren projects remove <name>               # remove a project (confirmation required)

phren mcp-mode [on|off|status]          # shared: user MCP, project-local: VS Code workspace MCP
phren hooks-mode [on|off|status]        # shared-mode only
phren config project-ownership [mode]   # default ownership for future project enrollments
phren config workflow set --taskMode=manual  # set task handling mode
phren config proactivity.findings [level]    # findings auto-capture aggressiveness
phren config proactivity.tasks [level]     # task auto-capture aggressiveness

phren skills list                       # list all installed skills
phren skills add <project> <path>       # add a skill to a project
phren skills enable <project|global> <name>   # enable a disabled skill without rewriting it
phren skills disable <project|global> <name>  # disable a skill without deleting it
phren skills remove <project> <name>    # remove a skill from a project
phren skill-list                        # alias for skills list

phren hooks list                        # show hook status per tool
phren hooks enable <tool>              # enable hooks for tool (claude/copilot/cursor/codex)
phren hooks disable <tool>            # disable hooks for tool

Use phren config for policy tuning and phren maintain for governance operations. Run --dry-run before destructive maintenance commands.

phren doctor

phren doctor checks your setup. --fix repairs what it can. --check-data also validates config files.

Access control (RBAC)

Four roles: admin, maintainer, contributor, viewer. Set in .governance/access-control.json. Identity comes from PHREN_ACTOR, then USER/USERNAME, then your OS username. Unknown actors default to viewer.

See docs/environment.md for all feature flags and env vars.

This repo has two roles: it's the source code for the phren npm package, and it ships the starter files that phren init copies to ~/.phren. The top-level directories break down like this:

starter/ vs templates/: starter/ is the full ~/.phren directory tree (projects, profiles, machines.yaml). templates/ holds the bare project skeleton used by the /phren-init skill. starter/templates/ holds typed project templates (frontend, library, etc.) used by phren init --template. Three layers: starter seeds the whole store, templates seeds the default project, starter/templates seeds typed projects.

Phren not injecting context into prompts

Run phren status and check the Hooks line. If it says "off", run phren hooks-mode on. If hooks are on but nothing's appearing, run phren doctor to check the prompt hook config. In project-local mode, hooks are intentionally unsupported.

MCP tools not connecting

Run phren status and check the MCP line. If it's off, run phren mcp-mode on. If cfg shows "missing", run phren init. In shared mode, MCP lands in user config files. In project-local mode, VS Code MCP lands in .vscode/mcp.json.

"I told phren something but can't find it"

Findings are scoped to a project. Try phren search "your term" --project <name>. If it was flagged by trust filtering, check the review queue: phren then press m.

Doctor says FAIL on symlinks

Project directory probably moved or symlinks are stale. Run phren doctor --fix.

Push failed or sync looks stuck

Run phren status first. If the store says saved-local, your data is committed locally and waiting on sync. The shell health view and web UI also show the last push error and unsynced commit count. Fix the remote or network issue, then let the background worker retry or run a normal git push yourself.

Hooks disabled or stale

Run phren hooks list. If the target tool is off or misconfigured, enable it again with phren hooks enable <tool> or rerun phren init.

Review queue keeps growing

Your trust policy is probably pushing too much low-confidence content into review. Triage with phren then m, or tune policy with phren config.

Governance writes are denied

Check .governance/access-control.json and your PHREN_ACTOR identity. Phren will refuse the write rather than silently forgetting it.

Merge conflicts after pulling on a new machine

Run phren and type :conflicts. Phren handles most merges on his own (task items, findings). If he can't resolve it, conflict markers show in the files for you.