Retorec Agent OS

What Is This Guide?

Retorec Agent OS is the operating infrastructure for the Retorec AI workforce. It is not a single tool — it is four interconnected systems that work together to make every Claude Code session smarter, better-equipped, and more integrated with the way your team actually works.

Agent vs Subagent

These two terms appear throughout the guide and in Claude Code daily — and they are easy to confuse because they sound similar but refer to completely different mechanisms.

Agent definitions — persona switches within one session

The 184 agents in retorec-agents/ are .md files. Each one contains a persona: a name, a role, a set of instructions, and a specialization. When Claude Code loads one, it changes how it thinks and communicates for the rest of that conversation. It is still one process, one session, one context window. No new process is started. The agent definition is simply a behavior layer on top of Claude.

You switch agents by typing a slash command (e.g. /ui-designer) or by naming the agent in a prompt. The same session continues — history is preserved, tools are the same, context accumulates. Switching from a Backend Architect agent to a UI Designer agent in the middle of a session is like handing the keyboard to a different specialist without leaving the room.

Subagents — separate Claude processes spawned on demand

A subagent is a completely separate Claude Code process. It is spawned when Claude uses the Agent tool internally, typically to handle a parallel or isolated task. Each subagent gets its own context window and starts with no memory of the parent session. It cannot see what you discussed earlier, it cannot read the parent's work-in-progress, and it does not share state. When it finishes, it returns one result back to the parent.

Subagents are useful for parallelizing independent research, running long tasks without bloating the main context, or getting a genuinely fresh second opinion. You will see them referenced in this guide when the Agents Orchestrator or Explore agents spawn workers to handle sub-tasks simultaneously.

GitHub SSH Setup

Retorec uses a shared GitHub account (github@retorec.com) for all repositories. Both founders connect to it using their own SSH key — one key per machine, all pointing to the same account. Commits are still attributed to each person's individual Retorec email.

Fadi's setup (already complete)

Fadi's machine has two SSH keys configured — a personal key and a Retorec key — with an SSH config that routes github-retorec to GitHub using the Retorec key. All Retorec repo remotes use git@github-retorec:Retorec/repo.git. No action needed on Fadi's side.

Mohammad — step by step

ssh-keygen -t ed25519 -C "github@retorec.com" -f ~/.ssh/id_ed25519_retorec

# Retorec GitHub
Host github-retorec
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_retorec
  AddKeysToAgent yes
  UseKeychain yes

cat ~/.ssh/id_ed25519_retorec.pub

ssh -T git@github-retorec

git clone git@github-retorec:Retorec/retorec-agent-os.git ~/Retorec/retorec-agent-os
git clone git@github-retorec:Retorec/retorec-agents.git ~/Retorec/retorec-agents

git config --global user.email "mohammad.binsabt@retorec.com"
git config --global user.name "Mohammad Binsabt Al Saeed"

Set up GitHub SSH access for my Retorec machine. Do the following steps in order:

1. Generate a new SSH key at ~/.ssh/id_ed25519_retorec using ed25519, with the comment "github@retorec.com" and no passphrase.
2. Add the key to the SSH agent (ssh-add ~/.ssh/id_ed25519_retorec).
3. Add this block to ~/.ssh/config (create the file if it doesn't exist, don't overwrite existing content):

Host github-retorec
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_retorec
  AddKeysToAgent yes
  UseKeychain yes

4. Print the full public key so I can copy it and send it to Fadi.
5. Tell me exactly what to say to Fadi so he can add it to GitHub.

Do not proceed past step 4 until I confirm Fadi has added the key. After I confirm, run: ssh -T git@github-retorec and show me the result.

Installing Retorec Agents

The retorec-agents repository contains 184 specialized Claude Code agents covering every function Retorec works in — from engineering and design to marketing, sales, finance, and beyond. Installing them gives every Claude Code session access to the full Retorec AI workforce. Agents are stored as markdown files and load automatically when you activate them by name during a session.

Agent Categories

The 184 agents are organized into 14 functional categories:

Installation Steps

git clone git@github-retorec:Retorec/retorec-agents.git ~/Retorec/retorec-agents

cd ~/Retorec/retorec-agents
./scripts/install.sh --tool claude-code

[OK]  Claude Code: 184 agents -> /Users/you/.claude/agents

Verifying the Install

After restarting, open Claude Code and type the prompt below. Claude will respond as the Engineering agent, confirming the agents are active and loaded.

List the names of 5 agents that are available in your agent roster, one from each of these categories: engineering, marketing, design, sales, and finance.

You can also verify the files landed on disk:

ls ~/.claude/agents/ | wc -l    # should print 184
ls ~/.claude/agents/ | head -10  # sample of installed agents

Keeping Agents Updated

The retorec-agents repo is updated regularly as new specialists are added and existing agents are refined. Run the following two commands to pull the latest and reinstall:

cd ~/Retorec/retorec-agents
git pull
./scripts/install.sh --tool claude-code

Then restart Claude Code. The install script overwrites existing agent files, so you always end up with the current version. No manual cleanup needed.

Install (or update) the Retorec agents on this machine. Do the following:

1. Check if ~/Retorec/retorec-agents/ already exists.
   - If it does not exist: clone it with git clone git@github-retorec:Retorec/retorec-agents.git ~/Retorec/retorec-agents
   - If it already exists: run git pull inside that directory to fetch the latest agents.
2. Run: cd ~/Retorec/retorec-agents && ./scripts/install.sh --tool claude-code
3. Confirm how many agents were installed and where they landed.
4. Tell me I need to restart Claude Code for the agents to be available, and remind me to do so.

Prerequisites

Before setting up a new machine, confirm these are installed:

node --version      # need v18 or higher
npm --version       # comes with Node
python3 --version   # used by the review scripts
git --version       # need git configured

If node is missing, install it from nodejs.org (LTS version).

Also confirm Claude Code is installed:

claude --version    # should return a version number

One-Time Machine Setup

Do this once per machine. Takes about 5 minutes.

mkdir -p ~/Retorec
git clone git@github-retorec:Retorec/retorec-agent-os.git ~/Retorec/retorec-agent-os

cd ~/Retorec/retorec-agent-os && git pull

cd ~/Retorec/retorec-agent-os/memory/scripts
npm install

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/extract-lessons.js"
          },
          {
            "type": "command",
            "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/save-session-summary.js"
          },
          {
            "type": "command",
            "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/save-session-progress.js"
          },
          {
            "type": "command",
            "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/extract-person-observations.js"
          }
        ]
      }
    ]
  }
}

SUPABASE_URL=https://nkdbaavjmrqkdpzzkrsr.supabase.co
SUPABASE_ANON_KEY=<from Fadi>
RETOREC_API_KEY=<from Fadi>
MEMORY_API_URL=https://memory-api-fawn.vercel.app
CLAUDE_API_KEY=<Anthropic API key>

Set up the Retorec memory system on this machine. Do the following steps in order:

1. If ~/Retorec/retorec-agent-os/ does not exist, clone it:
   git clone git@github-retorec:Retorec/retorec-agent-os.git ~/Retorec/retorec-agent-os
   If it already exists, run git pull inside it instead.

2. Run npm install inside ~/Retorec/retorec-agent-os/memory/scripts/ to install the hook dependencies.

3. Open ~/.claude/settings.json (create it if it does not exist). Add the following four Stop hooks,
   replacing YOUR_USERNAME with the actual macOS username (run `echo $USER` to find it).
   If the file already has content, merge the hooks block carefully — do not overwrite existing settings:

   "hooks": {
     "Stop": [
       { "matcher": "", "hooks": [
         { "type": "command", "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/extract-lessons.js" },
         { "type": "command", "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/save-session-summary.js" },
         { "type": "command", "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/save-session-progress.js" },
         { "type": "command", "command": "node /Users/YOUR_USERNAME/Retorec/retorec-agent-os/memory/scripts/extract-person-observations.js" }
       ]}
     ]
   }

4. Show me the final contents of ~/.claude/settings.json so I can verify the hooks are correct.

5. Tell me what I still need to do manually (the .env file) and what values it needs.

Per-Project Setup

Do this once per project, on each machine. This tags sessions with the correct project name.

mkdir -p ~/Retorec/projects/your-project/.claude
echo 'PROJECT_NAME=your-project-name' > ~/Retorec/projects/your-project/.claude/project.env

mkdir -p ~/Retorec/projects/your-project/scripts
cp ~/Retorec/projects/velo/scripts/identity.sh       ~/Retorec/projects/your-project/scripts/
cp ~/Retorec/projects/velo/scripts/review-lessons.sh ~/Retorec/projects/your-project/scripts/
cp ~/Retorec/projects/velo/scripts/review-skills.sh  ~/Retorec/projects/your-project/scripts/
cp ~/Retorec/projects/velo/scripts/save-lesson.sh    ~/Retorec/projects/your-project/scripts/
cp ~/Retorec/projects/velo/scripts/memory-lessons.sh ~/Retorec/projects/your-project/scripts/
chmod +x ~/Retorec/projects/your-project/scripts/*.sh

export PROJECT_NAME="${PROJECT_NAME:-your-project-name}"

cd ~/Retorec/projects/your-project
git config user.email "mohammad.binsabt@retorec.com"

Set up the Retorec memory system for this project. The project name is [YOUR-PROJECT-NAME] (lowercase, hyphens only).
The project lives at ~/Retorec/projects/[YOUR-PROJECT-NAME]/.

Do the following:

1. Create the directory ~/Retorec/projects/[YOUR-PROJECT-NAME]/.claude/ if it does not exist.
2. Write the file ~/Retorec/projects/[YOUR-PROJECT-NAME]/.claude/project.env with this content:
   PROJECT_NAME=[YOUR-PROJECT-NAME]
3. Create ~/Retorec/projects/[YOUR-PROJECT-NAME]/scripts/ if it does not exist.
4. Copy these five scripts from ~/Retorec/projects/velo/scripts/ into that folder:
   identity.sh, review-lessons.sh, review-skills.sh, save-lesson.sh, memory-lessons.sh
5. Make all copied scripts executable with chmod +x.
6. Open identity.sh and update the fallback PROJECT_NAME value to [YOUR-PROJECT-NAME].
7. Run: cd ~/Retorec/projects/[YOUR-PROJECT-NAME] && git config user.email "mohammad.binsabt@retorec.com"
8. Confirm every step completed and show me the contents of .claude/project.env to verify.

Directory Structure

Understanding where everything lives is essential for both founders. The structure below is the single source of truth — reproduce it exactly on Mohammad's machine so paths, scripts, and hook commands all match.

Global Retorec workspace — ~/Retorec/

Every Retorec repository and project lives under ~/Retorec/. This is a hard convention — never save project files to the Desktop, Downloads, or any other location.

~/Retorec/
├── retorec-agent-os/          ← AI workforce infrastructure (this repo)
│   ├── dna/
│   │   └── rules/             ← identity.md, brand-system.md, methodology.md, project-structure.md
│   ├── memory/
│   │   └── scripts/           ← Hook scripts: extract-lessons.js, save-session-summary.js,
│   │                              save-session-progress.js, extract-person-observations.js,
│   │                              synthesize.js, show-profile.js
│   ├── tools/
│   │   └── m365/              ← Microsoft 365 MCP server: auth.js, graph.js, backlog.js,
│   │                              docgen-docx.js, docgen-pptx.js, index.js
│   ├── workflows/             ← Workflow templates and references
│   └── .env                   ← Global credentials (Supabase, API keys) — one file, never copied
│
├── retorec-agents/            ← 184 specialized Claude Code agent definitions
│   ├── academic/
│   ├── design/
│   ├── engineering/
│   ├── finance/
│   ├── game-development/
│   ├── marketing/
│   ├── paid-media/
│   ├── product/
│   ├── project-management/
│   ├── sales/
│   ├── spatial-computing/
│   ├── specialized/
│   ├── support/
│   └── testing/
│
├── _global/                   ← Shared non-code Retorec resources
│   ├── brand/                 ← Logos, brand guidelines, profile PDF
│   ├── finance/               ← Budgets, projections
│   ├── legal/                 ← Contracts, compliance, registration
│   ├── research/              ← Market reports, competitor analysis
│   ├── strategy/              ← Pipeline, partnerships, roadmaps
│   └── templates/             ← Reusable decks, proposals, onboarding docs
│
├── DNA-Guide/
│   └── agents-guide.md        ← Narrative guide to the 184 agents
│
└── projects/                  ← All Retorec projects live here (see layout below)
    ├── <project-a>/           ← Each follows the standard per-project layout
    ├── <project-b>/
    └── <project-c>/           ← No separate repo per project — all tracked here

Per-project layout — ~/Retorec/retorec-agent-os/projects/<name>/

Every project follows this exact structure. Agents enforce it — any file saved to the wrong location gets moved back on the next session.

~/Retorec/retorec-agent-os/projects/<project-name>/
├── CLAUDE.md                  ← Project brief for all agents (committed to git)
├── CLAUDE.local.md            ← Personal overrides — never committed
├── .gitignore
│
├── .claude/
│   ├── settings.json          ← Shared tool permissions (committed)
│   ├── settings.local.json    ← Personal permission overrides (gitignored)
│   ├── project.env            ← PROJECT_NAME tag — hooks use this to attribute sessions
│   ├── commands/              ← Project-specific slash commands
│   ├── rules/                 ← Project-specific instruction files
│   ├── agents/                ← Project-specific agent definitions
│   └── memory/                ← Auto-memory files written by Claude (gitignored)
│
├── docs/                      ← PRDs, specs, wireframes, diagrams (HTML/MD/PDF)
├── scripts/                   ← Shell helpers: review-lessons.sh, synthesize.sh, etc.
│
├── src-<project-name>/
│   ├── backend/               ← Node.js / Express API
│   ├── mobile/                ← React Native apps (one subfolder per app)
│   └── web/                   ← React web apps (one subfolder per app)
│
└── operation/                 ← Post-launch operations and automation (committed to git)
    ├── ops.md                 ← Live operational brief — agents read this
    ├── reporting/             ← Dashboards, KPI definitions, data exports (exports/ gitignored)
    ├── customer-service/      ← Templates, playbooks, SLAs (tickets/ gitignored)
    ├── knowledge/             ← Product docs, runbooks, improvement log
    ├── presence/              ← Brand, social strategy, web copy, news
    ├── roadmap/               ← Backlog and release planning
    └── incidents/             ← Incident log and post-mortems

Local folder → GitHub mapping

Everything lives in one private repo: github.com/Retorec/retorec-agent-os. The table below shows how each local directory maps to its path inside that repo.

Collaboration Agents — Why They Exist

Two agents exist specifically for Retorec's two-founder workflow. They are not general-purpose tools — they encode the exact setup standard and daily discipline that keeps both developers in sync without any manual coordination overhead.

/retorec-project-setup

Start a Claude Code session from any directory — you do not need to create the project folder first. The agent creates everything using absolute paths inside ~/Retorec/retorec-agent-os/projects/.

What the agent asks you

If you say "use defaults", it proceeds with the Retorec standard stack.

What it creates

~/Retorec/projects/<name>/
├── .claude/{commands, rules, agents}
├── memory/{fadi, mhd}           ← committed to git
├── docs/
├── scripts/
├── src-<name>/{backend, mobile, web}
└── design/{wireframes, assets}

One-time setup flow

# 1. Open Claude Code from anywhere
# 2. /retorec-project-setup
# Done — project is at ~/Retorec/retorec-agent-os/projects/<name>/ and live on GitHub

# Mohammad (gets the new project automatically):
cd ~/Retorec/retorec-agent-os
git pull

/retorec-session-start

Start Claude Code from inside ~/Retorec/projects/<name>/ — the agent reads .claude/project.env to identify the project. It then runs the full briefing sequence automatically, no prompts needed.

What it runs (in order)

Briefing output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SESSION START — velo
  Developer: Fadi · 11 May 2026
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SYNC
  2 commits pulled
  · Mohammad — "Complete driver onboarding flow"
  · Mohammad — "Fix auth token refresh on 401"

PARTNER UPDATE  (Mohammad)
  · Completed driver onboarding — signup, document upload, approval flow
  · Auth token refresh now handles 401s automatically
  · Working on trip state machine (in_progress per his memory)

YOUR OPEN ITEMS  (from memory/fadi/)
  · Passenger app map screen — waiting on trip state machine API
  · Review push notification provider decision (open question)

SHARED OPEN QUESTIONS
  · Push notification provider not decided — Firebase vs OneSignal

REPO STATE
  Branch: main
  Clean: yes
  Ahead of origin: no

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Ready. What are you working on today?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Daily habit

cd ~/Retorec/projects/<project-name>
# Open Claude Code here
/retorec-session-start
# ... do your work ...
git add memory/fadi/   # or memory/mhd/
git commit -m "..."
git push

The briefing stays under 30 lines every time. If both memory directories are empty (early in a project), it notes that and moves on — it never errors on missing data.

Operation Directory — Post-Launch Management

Once a product is live, the work doesn't stop at the code — it shifts. Reporting needs to be tracked, customers need to be supported, knowledge needs to be documented, the brand needs to be maintained, and incidents need to be logged. The operation/ directory is the structured home for all of that. Its purpose is twofold: to manage the product's live operations, and to automate them by giving agents a clear, consistent place to read context and take action.

Agents working on a live project need to know more than just the code — they need to know the current operational status, what customers are saying, what's in the roadmap, what incidents have occurred, and what the brand guidelines are. The operation/ directory puts all of that in one committed, structured location so any agent — whether handling customer service, drafting a release note, updating the social calendar, or triaging an incident — has everything it needs without being told where to look.

Directory Structure

The operation/ tree is standard across all Retorec projects. Two subdirectories are gitignored due to PII risk; everything else is committed.

operation/
├── ops.md                        ← live operational brief (agents read this)
├── reporting/
│   ├── dashboards/               ← Power BI .pbix files, Excel workbooks
│   ├── kpis/                     ← KPI definitions, targets, tracking docs
│   └── exports/                  ← ⛔ gitignored — raw data dumps / PII
├── customer-service/
│   ├── templates/                ← response templates and macros
│   ├── scripts/                  ← escalation playbooks, issue resolutions
│   ├── slas/                     ← SLA definitions and response time targets
│   └── tickets/                  ← ⛔ gitignored — live ticket data / PII
├── knowledge/
│   ├── product/                  ← what it does, how it works, user FAQs
│   ├── runbooks/                 ← operational how-tos, deploy, rollback
│   └── improvements/             ← logged issues, feature requests
├── presence/
│   ├── brand/                    ← project brand assets and guidelines
│   ├── social/
│   │   ├── strategy/             ← platform strategy, audience, tone
│   │   └── content/              ← drafts, published pieces, calendar
│   ├── web/                      ← web copy updates, SEO notes
│   └── news/                     ← release notes, feature announcements
├── roadmap/
│   ├── backlog/                  ← feature requests from users and ops data
│   └── releases/                 ← past and upcoming releases
└── incidents/                    ← incident log and post-mortems

ops.md — The Operational Brief

operation/ops.md is the live operational brief for the product. It's the equivalent of CLAUDE.md for post-launch operations — agents read it to understand the current state of the product without needing to ask. It's updated by developers whenever something meaningful changes: a release ships, an incident resolves, a KPI target changes.

# <Project Name> — Operations Brief

**Status**: pre-launch
**Live since**: <!-- update on launch date -->
**Current version**: 0.1.0
**Last updated**: <date>

---

## Product Summary
<!-- One sentence: what this product does and who it's for -->

## Environments
| Environment | URL   | Notes |
|-------------|-------|-------|
| Production  | —     |       |
| Staging     | —     |       |

## Current State
**Operational status**: healthy / degraded / incident

**Active priorities**:
- <!-- what the team is focused on right now -->

**Known issues**:
- <!-- production bugs or limitations operators should be aware of -->

## Recent Releases
| Version | Date | What changed |
|---------|------|-------------|
|         |      |              |

## Key Metrics
| Metric | Target | Current |
|--------|--------|---------|
|        |        |         |

## Customer Service
**Support channel**: <!-- email / chat / in-app -->
**SLA — first response**: <!-- e.g. 4 business hours -->
**Escalation contact**: Fadi Jalajel

## Contacts & Ownership
| Area                 | Owner                     |
|----------------------|---------------------------|
| Technical issues     | Fadi Jalajel              |
| Business / strategy  | Mohammad Binsabt Al Saeed |
| Customer escalations | Fadi Jalajel              |

## Operational Notes
<!-- Quirks, manual processes, external dependencies -->

Setting Up the Operation Directory

If you're using /retorec-project-setup, the operation/ directory and ops.md are created automatically — nothing to do. For an existing project that doesn't have it yet:

cd ~/Retorec/projects/<name>

# Create all subdirectories
mkdir -p operation/{reporting/{dashboards,kpis,exports},customer-service/{templates,scripts,slas,tickets},knowledge/{product,runbooks,improvements},presence/{brand,social/{strategy,content},web,news},roadmap/{backlog,releases},incidents}

# Add .gitkeep so git tracks empty dirs
find operation -type d -exec touch {}/.gitkeep \;

# Add gitignore entries (append to existing .gitignore)
echo "operation/reporting/exports/" >> .gitignore
echo "operation/customer-service/tickets/" >> .gitignore

# Create ops.md from the template (copy from project-structure.md or write manually)
# Then commit everything
git add operation/ .gitignore
git commit -m "Add operation/ directory structure"

The Learning Loop

Architecture & Storage

The memory system supports two interchangeable storage backends, controlled by a single environment variable. SharePoint is the default — it costs nothing extra (included in M365) and writes directly to SharePoint Lists via the Microsoft Graph API. The Supabase + Vercel backend remains fully operational as an alternative.

Backend Configuration

A single environment variable selects which backend all memory scripts use. Set it in ~/Retorec/retorec-agent-os/.env:

If the variable is absent, SharePoint is used. No other code changes are required — the backends/index.js selector automatically routes all hook scripts and CLI tools to the correct adapter.

SharePoint Lists (Default Backend)

Seven SharePoint Lists, each prefixed Memory_, replace the Supabase tables one-for-one. They live on your M365 tenant at https://retorec.sharepoint.com/Lists/ and are managed entirely via the Microsoft Graph API — no additional subscriptions or infrastructure needed.

One-time setup

Run this once to create all seven lists with the correct columns:

node ~/Retorec/retorec-agent-os/memory/scripts/setup-sharepoint.js

The script is safe to re-run — it skips lists that already exist. Once created, the lists are shared across all machines and founders (same M365 tenant).

The seven Memory_* lists

Reviewing lessons in SharePoint

The review-lessons.sh bash script is Supabase-only. When using SharePoint, review and approve lessons directly in the SharePoint list UI:

1. Open https://retorec.sharepoint.com/Lists/Memory_Lessons
2. Filter by Status = pending
3. Read each lesson and set Status to approved (to activate it) or rejected (to discard)
4. To edit the lesson text before approving, click the row and edit the Lesson field inline

Applying evolution suggestions in SharePoint

When synthesis proposes that a lesson should be superseded, apply it manually:

1. Open Memory_Lessons, find the item by its SharePoint ID
2. Set Status → superseded
3. Optionally set SupersededBy to the ID of the replacement lesson

Supabase Tables (Alternative Backend)

When MEMORY_BACKEND=supabase, all scripts route through the Vercel Memory API (https://memory-api-fawn.vercel.app) backed by PostgreSQL on Supabase. This backend is fully operational and requires no changes to use.

For a full list of Supabase tables and the REST API endpoints, see API Endpoints Reference →

What Gets Stored

Seven data stores in the active backend. Each serves a different part of the loop:

Shared Developer Memory

Every project has a memory/ directory at its root — committed to Git and shared between all developers. When Fadi's Claude writes something to memory, Mohammad's Claude sees it on the next git pull, and vice versa. No manual handoff needed.

How Claude routes automatically

The CLAUDE.md in every project contains a Shared Memory block that instructs Claude to determine the active developer from git config user.email and write to the correct directory. No manual switching — it is automatic.

What belongs in memory files

Setting Up Shared Memory

New projects

The setup command in the project structure standard creates the directories automatically:

mkdir -p ~/Retorec/projects/<name>/{memory/{fadi,mhd}, ...}
touch memory/fadi/.gitkeep memory/mhd/.gitkeep
git add memory/
git commit -m "Add shared memory directories"

Existing projects (retrofit)

cd ~/Retorec/projects/<project>
mkdir -p memory/fadi memory/mhd
touch memory/fadi/.gitkeep memory/mhd/.gitkeep
git add memory/
git commit -m "Add shared memory directories"
git push

Mohammad gets both directories the moment he pulls. No further setup needed on his end.

Add the Shared Memory block to CLAUDE.md

Copy this verbatim into every project's CLAUDE.md:

## Shared Memory

At the start of every session:
1. Read ALL files in memory/fadi/ and memory/mhd/
2. Treat their contents as active project context — decisions made, current
   state, open questions, patterns established

When writing memory during or at the end of a session:
- Determine the active developer from: git config user.email
  - fadi.jalajel@retorec.com       → write to memory/fadi/
  - mohammad.binsabt@retorec.com   → write to memory/mhd/
- Keep memory files focused: decisions, current state, open questions, patterns
- Never write credentials, personal notes, or session-specific ephemera

At the end of every session:
- Commit and push memory/ along with any other session changes

Daily & Weekly Rhythm

The system has three operating tempos. Know which is automatic and which you trigger manually.

How Hooks Work (Automatic)

Every time a Claude Code session ends, four scripts fire in the background. You do not trigger these — Claude Code handles it.

Verifying hooks fired

After a session ends, wait a few seconds then run:

cd ~/Retorec/projects/your-project
bash scripts/review-lessons.sh

If lessons appear in the review UI, the hooks fired correctly.

Reviewing Lessons

Run this whenever you want to process the pending lesson queue. Batch after every few sessions, or review daily — whatever fits your rhythm.

Supabase backend — interactive terminal review:

cd ~/Retorec/projects/your-project
bash scripts/review-lessons.sh

The script shows each pending lesson one at a time:

╔══════════════════════════════════════════╗
║        Retorec Lesson Review             ║
╚══════════════════════════════════════════╝
  Project: velo   Pending: 3

┌─ Lesson 1 of 3 ── ↑ seen 3x

  Always quote URLs containing ? in zsh — unquoted ? triggers glob expansion

  Importance:  high
  Scope:       global
  From:        fadi.jalajel@retorec.com @ Fadis-MacBook-Pro.local

  [s] save  [e] edit  [k] skip  [q] quit
  → 

The ↑ seen Nx badge shows how many times this lesson was extracted across different sessions. Seen 4 times = much stronger signal than seen once. Prioritize those.

Saving a Manual Lesson

To save a lesson directly — after a conversation, a decision, or something you just know — without going through the review flow:

bash scripts/save-lesson.sh <project> "lesson text" <importance> <scope>

bash scripts/save-lesson.sh velo \
  "Always validate the API response before rendering — never trust shape." \
  high global

bash scripts/save-lesson.sh velo \
  "The driver rating algorithm uses a 30-day rolling window, not lifetime." \
  medium project

Importance: low / medium / high  ·  Scope: global / project

Viewing Active Lessons

To see all approved active lessons for this project:

bash scripts/memory-lessons.sh

Agents automatically load these at the start of every session — so everything approved here actually influences future work.

Running Synthesis

Once a week (or whenever the lesson base feels substantial), run the synthesis job. It needs at least 2 approved lessons to run.

cd ~/Retorec/projects/your-project
node ~/Retorec/retorec-agent-os/memory/scripts/synthesize.js

🔬 Retorec Synthesis — velo
──────────────────────────────────────────────────
Fetching approved lessons...  Found 8 active lessons
Running AI synthesis...

── Summary ──────────────────────────────────
The knowledge base reflects patterns around API safety, zsh shell quirks,
and identity resolution.

── Themes (3) ──────────────────────────────
  • Shell Safety (3 lessons)
  • API Defensive Patterns (2 lessons)
  • Identity Resolution (1 lesson)

── Skill Candidates (2) ────────────────────
  • zsh URL Quoting Guard
  • API Response Validation Pattern

Staging 2 skill candidate(s) for review...
✓ Synthesis complete.

Reviewing Skills

After synthesis, review the proposed skill candidates.

Supabase backend — interactive terminal review:

bash scripts/review-skills.sh

╔══════════════════════════════════════════╗
║        Retorec Skill Review              ║
╚══════════════════════════════════════════╝
  Project: velo   Pending: 2

┌─ Skill 1 of 2 ──────────────────────────────

  zsh URL Quoting Guard

  Description:
  Always wrap URLs containing ? or & in double quotes in zsh shell scripts
  to prevent glob expansion from silently corrupting query parameters.

  Trigger context:
  Any time a curl command contains query string parameters

  Scope: global

  [a] approve  [k] skip  [r] reject  [q] quit
  → 

Human Profiles — Understanding Your Team

Every Claude session now quietly observes the human participating in it. Over many sessions, these observations accumulate into a living profile — a structured picture of each person's knowledge, skills, interests, creativity, and how they work. Profiles are never injected into agent context automatically. They are private, on-demand, and built purely from evidence in actual transcripts.

How Profiles Build Up

At the end of every session, the fourth Stop hook — extract-person-observations.js — reads the transcript and asks Claude Opus to extract 3 to 5 observations about the human participant. It identifies the person from their git email, upserts a record in the persons table, and saves each observation directly to person_observations. No pending queue. No review step. The data just accumulates.

Each observation is tagged with the session ID, project name, category, the observation itself, and a short evidence reference — a 5–10 word pointer to what in the transcript led to it. This means every profile claim is grounded in actual evidence, not guesswork.

Observation Categories

Seven categories. Each captures a different dimension of the person:

Viewing a Profile

Profiles are never shown automatically. You request them by running show-profile.js with an email address. Claude Opus reads all accumulated observations for that person and synthesizes them into a structured 8-section report printed directly in your terminal.

List all persons in the system

node ~/Retorec/retorec-agent-os/memory/scripts/show-profile.js --list

Persons in the system:

  fadi.jalajel@retorec.com — Fadi Jalajel (Co-Founder, Deputy CEO)
  mohammad.binsabt@retorec.com — Mohammad Binsabt Al Saeed (Co-Founder, CEO)

Generate a profile

node ~/Retorec/retorec-agent-os/memory/scripts/show-profile.js fadi.jalajel@retorec.com

Fetching observations for fadi.jalajel@retorec.com...
Found 24 observations across 8 sessions.

Generating profile...

════════════════════════════════════════════════════════════
  PROFILE: fadi.jalajel@retorec.com
════════════════════════════════════════════════════════════

1. Overview
Fadi Jalajel is Co-Founder and Deputy CEO of Retorec, operating as both
a strategic leader and hands-on product builder. Across observed sessions
he consistently drives from problem definition to working code, with
minimal time spent in abstract planning...

2. Knowledge & Expertise
Demonstrates strong command of AI agent infrastructure, memory system
architecture, PostgreSQL, and Node.js API design. Familiar with Vercel
deployment, SSH key management, and GitHub workflows...

3. Skills
Capable of diagnosing and resolving API integration issues in real time.
Able to orchestrate multi-step technical builds across backend, database,
and deployment layers simultaneously...

4. Acquired Skills
Now understands how Claude Code Stop hooks fire and how transcript data
is passed to external scripts via stdin. Learned SSH host alias routing
during the GitHub setup session...

5. Interests & Recurring Themes
Consistently returns to compounding AI intelligence — the idea that
agents should get smarter with every interaction. Strong recurring
interest in the Retorec Memory System and its expansion...

6. Creativity & Problem-Solving
Proposed the Human Profile System as a natural extension of the memory
loop — reframing session transcripts as observations about people rather
than just project knowledge. Novel and immediately implementable...

7. Work Style & Communication
Requests are direct and action-oriented. Prefers index-first delivery
for large outputs. Rarely asks for explanations of the obvious. Moves
fast once a direction is agreed...

8. Decision Patterns
Consistently chooses speed over ceremony — opted for no-review model
for profile observations, chose Vercel over self-hosted for the API,
cut Obsidian integration when the ROI was unclear...

Working with this person: Move fast and be decisive — Fadi responds well
to confident recommendations with clear tradeoffs. Lead with the actionable
output; keep explanations tight and tied to what he is building right now.

════════════════════════════════════════════════════════════

Each section is synthesized purely from accumulated observations — nothing is invented. The more sessions run, the richer the profile becomes. Early profiles (fewer than 5 sessions) will be sparse; after 10–15 sessions they become genuinely detailed.

Using Profiles Effectively

When to generate a profile

• Onboarding a new agent to a person — copy the profile output into the agent's context before a high-stakes session.
• Quarterly team reviews — run profiles for all team members to see how knowledge and skills have evolved.
• Handing off a project — generate the profile of the departing owner so the incoming person (or agent) understands how they worked.
• Checking learning progress — the acquired_skill category shows what each person has learned over time.

Privacy design

Profiles are not automatically loaded into any agent's context. An agent only sees a profile if you explicitly paste it in. This is intentional — profile data is detailed and personal, and should be shared with agents only when the context calls for it.

Running a profile for Mohammad

Once Mohammad's machine is set up with the correct git email and hooks configured, his sessions will automatically build his profile. Run this from either machine to view it:

node ~/Retorec/retorec-agent-os/memory/scripts/show-profile.js mohammad.binsabt@retorec.com

M365 Integration — OneDrive, Excel, Word & PowerPoint

The Retorec M365 MCP server is a custom-built integration that gives Claude Code agents direct, programmatic access to Microsoft 365 — specifically OneDrive file storage, Excel workbooks, Word document generation, and PowerPoint presentation generation. It is built and owned by Retorec, using Microsoft's official MSAL authentication library and the Microsoft Graph API. No third-party services are involved.

Activating the MCP Server

The server is already built, installed, and registered. One-time activation:

cat ~/Retorec/retorec-agent-os/tools/m365/.env

what MCP tools do you have available?

8 Tools at a Glance

Test 1 — Browse Your OneDrive

List the files and folders in my OneDrive root. My email is fadi.jalajel@retorec.com

List the files inside the "Documents" folder in my OneDrive. Email: fadi.jalajel@retorec.com

Test 2 — Upload a File to OneDrive

Create a text file at /tmp/hello-retorec.txt with the content "Retorec M365 test — uploaded by agent" and upload it to my OneDrive at "Retorec-Tests/hello.txt". My email is fadi.jalajel@retorec.com

Test 3 — Download a File from OneDrive

Download the file "Retorec-Tests/hello.txt" from my OneDrive and tell me what it contains. My email is fadi.jalajel@retorec.com

Test 4 — Read an Excel File

Read the data from the Excel file at "Documents/budget.xlsx" in my OneDrive. Read the first sheet, range A1:E10. My email is fadi.jalajel@retorec.com

Test 5 — Write to an Excel File

Write the following data to "Documents/budget.xlsx" in my OneDrive, Sheet1, starting at cell A1:
Headers: Month, Revenue, Expenses, Profit
Row 1: January, 50000, 32000, 18000
Row 2: February, 62000, 35000, 27000
Row 3: March, 58000, 31000, 27000
My email is fadi.jalajel@retorec.com

Test 6 — Convert a File to PDF

Convert the file "Documents/budget.xlsx" in my OneDrive to PDF and tell me where it was saved. My email is fadi.jalajel@retorec.com

Test 7 — Create a Word Document

Create a Word document titled "Q2 Project Brief" with the following content:
- A subtitle: "Retorec AI Workforce"
- Author: Fadi Jalajel
- Section heading "Objectives" with a bullet list: Deploy 50 agents, Integrate M365, Launch client pilot
- Section heading "Budget" with a table: columns are Item / Cost / Timeline, rows are: Agent infrastructure / $12,000 / Q2 | M365 integration / $3,500 / May | Client pilot / $8,000 / June
Then upload it to my OneDrive at "Documents/Q2-Brief.docx". My email is fadi.jalajel@retorec.com

Test 8 — Create a PowerPoint

Create a PowerPoint presentation titled "Retorec Q2 Strategy" using the retorec dark theme with these slides:
1. Title slide: "Retorec Q2 Strategy", subtitle "AI Workforce Expansion", footer "Confidential"
2. Content slide titled "Key Objectives" with bullets: Deploy 50 agents by June / Full M365 integration live / First external client pilot launched
3. Table slide titled "Budget Summary" with columns Item / Cost / Timeline and rows: Agent infrastructure / $12,000 / Q2 | M365 integration / $3,500 / May | Client pilot / $8,000 / June
4. Split slide titled "Risks vs Opportunities" — left side bullets: Timeline pressure / Auth complexity — right side bullets: First mover in Kuwait / Compounding DNA
5. Blank slide: title "Always Aim Higher", content "retorec.com"
Then upload it to my OneDrive at "Presentations/Q2-Strategy.pptx". My email is fadi.jalajel@retorec.com

Full Agent Workflow — Brief to Deliverable

This is the complete pattern agents follow: read a brief from OneDrive, do the work, produce a deliverable, save it back. You can trigger this with a single prompt.

Read the brief at "Briefs/client-brief.docx" from my OneDrive (fadi.jalajel@retorec.com),
understand the requirements, then create a proposal as a Word document and a summary deck
as a PowerPoint. Save both to "Deliverables/client-proposal.docx" and
"Deliverables/client-proposal.pptx" in my OneDrive.

The agent will:

1. Call download_file to pull the brief locally
2. Read and analyze the content
3. Call create_word_document with a structured proposal
4. Call upload_file to save the DOCX
5. Call create_powerpoint with a summary deck
6. Call upload_file to save the PPTX

M365 API endpoints reference

Scrum Backlog — Microsoft Lists

The Scrum Backlog integration stores all software development work items inside Microsoft Lists (SharePoint) — zero extra cost, fully integrated with your M365 tenant. Agents can create epics, stories, tasks, bugs, and spikes; move items through a sprint; and render a live sprint board — all via natural language prompts.

Item types & statuses

One-Time Setup

Run setup_backlog once. It checks whether the SharePoint list already exists — if not, it creates it and provisions all custom columns automatically. After that, the list is ready to use forever.

Use the setup_backlog tool to initialise the Retorec Backlog list on SharePoint.
Tell me the list URL when done so I can bookmark it.

5 Tools at a Glance

Test: Setup Backlog

Run setup_backlog and show me the SharePoint list URL.

✓ "Retorec Backlog" created successfully.
  List ID : <guid>
  Site ID : <guid>
  URL     : https://retorec.sharepoint.com/Lists/Retorec%20Backlog
  Columns : 10/10 created

Next: use create_backlog_item, list_backlog_items, update_backlog_item, get_sprint_board.

Test: Create a Backlog Item

Create a Story in the backlog: "As a user I can log in with my email and password."
Priority: High. Story points: 5. Sprint: Sprint 1.
Acceptance criteria: login succeeds with valid credentials; login fails with invalid credentials.

Created #2 [Story] "As a user I can log in with my email and password." [5pts]
Status: Backlog | Priority: High | Sprint: Sprint 1

Test: List Backlog Items

List all backlog items in Sprint 1.

3 item(s) found:

── Story (2) ──
  #2  As a user I can log in with my email and password. [5pts]  —  Backlog | High | Sprint 1
  #3  As a user I can reset my password via email. [3pts]  —  Backlog | Medium | Sprint 1

── Task (1) ──
  #4  Set up CI/CD pipeline  —  Backlog | High | Sprint 1

Test: Update a Backlog Item

Move backlog item #2 to "In Progress" and assign it to Fadi.

Updated #2: Status → In Progress | AssignedTo → Fadi

Test: Sprint Board

Show me the sprint board for Sprint 1.

Sprint Board: Sprint 1
─────────────────────────────────────────
Items: 1/4 done   Points: 3/16 (19%)

── In Sprint (1) ──
  • #4 [Task] Set up CI/CD pipeline — Fadi

── In Progress (1) ──
  • #2 [Story] As a user I can log in with my email and password. (5pts) — Fadi

── In Review (0) ──
  (empty)

── Done (1) ──
  • #3 [Story] As a user I can reset my password via email. (3pts)

── Cancelled (0) ──
  (empty)

Scrum Workflow with Agents

Agents can run every Scrum ceremony as a conversational flow. Here is the standard pattern for each event.

Sprint Planning

At the start of a sprint, define items and assign them to the sprint.

We're starting Sprint 2. Pull everything in the backlog with status "Ready" and move
them into Sprint 2. Assign the 3 highest-priority stories to Fadi and the rest to the
team backlog. Show me the sprint board when done.

Daily Standup

Ask for a snapshot of what's in flight across the team.

Give me a daily standup summary for Sprint 2: what's In Progress, what's In Review,
and what's blocked or hasn't moved since yesterday's sprint board.

Moving Items Through the Board

During the sprint, agents update status as work progresses.

Item #7 is done — move it to Done. Item #9 is blocked — add a note in its description
and move it back to In Sprint. Show me the updated board.

Sprint Review & Retrospective

At the end of a sprint, get a completion summary and close out the sprint.

Sprint 2 is over. Show me the final sprint board. Cancel any items still In Sprint
that weren't started. List all Done items with their story points so I can calculate
velocity. Then create these 4 new stories in the backlog for Sprint 3: [list them].

Telegram Inbox — Project Communication Channel

Every Retorec project gets a dedicated Telegram group with a bot. Founders use it as a live channel to send instructions, share insights, forward meeting notes, drop files, and record voice memos — all from any device, at any time. The bot receives everything, classifies it, saves it to a shared Microsoft List, and posts a confirmation back to the group. At the next Claude Code session, unread items surface automatically in the briefing. Nothing gets lost.

How It Works

The flow for a normal message (no !go):

Founder sends anything to the project Telegram group
        ↓
Bot receives message
        ↓
1. Download media if present (voice/image/file/video)
2. Transcribe audio  →  Claude Haiku Whisper-style
   Describe image    →  Claude Haiku Vision
   Upload file       →  SharePoint document library
        ↓
3. Classify with Claude Haiku:
   type: text / voice / image / file / video
   intent: instruction / insight / update / meeting-note / file / question
        ↓
4. Save record to Retorec_ProjectInbox (Status = new)
        ↓
5. Post confirmation back to the group:
   "✓ Voice message received — classified as instruction
    Saved to inbox. Review it at your next session with /retorec-inbox"

At session start, /retorec-session-start queries the list and surfaces the count:

INBOX
  3 unread Telegram messages — run /retorec-inbox to review

The !go Trigger

Prefix any message with !go (case-insensitive: !go, !Go, !GO) to bypass the review queue and execute immediately. The bot interprets the instruction, writes the appropriate file into the project directory, updates the list, and reports back — all within seconds of sending.

Fadi sends:  "!go Add Apple Pay support to the checkout flow in the velo backlog"

Bot replies in the group (within ~5 seconds):
  ⚡ !go executed
  Added Apple Pay support requirement to backlog

  → Written to ~/Retorec/projects/velo/operation/roadmap/backlog/apple-pay-2026-05-14.md

Fadi sends:  "!go Meeting with Kuwait Airways today. Decision: we build the
              mobile app first, web portal in Q3. Budget approved at KD 45,000."

Bot replies:
  ⚡ !go executed
  Recorded meeting decision — Kuwait Airways engagement scope

  → Written to ~/Retorec/projects/velo/operation/knowledge/product/kuwait-airways-decision-2026-05-14.md

Fadi sends:  "!go fix the thing we discussed"

Bot replies:
  ⚠ !go — needs more context
  Instruction was unclear — no specific action could be determined.
  Added to your review queue. Run /retorec-inbox to clarify.

When an instruction is ambiguous, the bot downgrades it to Status = new — it appears in the review queue at your next session so nothing falls through the cracks.

Media Support

Setting It Up — Per Project

One-time setup per project. The SharePoint list is shared — create it once for all projects.

cd ~/Retorec/retorec-agent-os/tools/telegram-inbox
npm install
cp projects/.env.example projects/.env.velo   # edit this first
npm run setup-list

node scripts/get-site-id.js

# projects/.env.velo
PROJECT_NAME=velo
TELEGRAM_BOT_TOKEN=<from BotFather>
TELEGRAM_CHAT_ID=<negative number from getUpdates>
MS_TENANT_ID=<same as your M365 MCP server .env>
MS_CLIENT_ID=<same as your M365 MCP server .env>
MS_CLIENT_SECRET=<same as your M365 MCP server .env>
SHAREPOINT_SITE_ID=<from get-site-id.js>
ANTHROPIC_API_KEY=<your Anthropic key>

npm install -g pm2
./deploy.sh

pm2 list
pm2 logs telegram-inbox-velo

cp projects/.env.velo projects/.env.<new-project>
# Edit the new file — change PROJECT_NAME, TOKEN, CHAT_ID
cp projects/velo.config.json projects/<new-project>.config.json
# Edit projectName and projectDir in the config
./deploy.sh   # picks up the new .env file automatically

git pull origin main   # get latest core/ changes
./deploy.sh            # restarts all running bots

/retorec-inbox — Reviewing Your Queue

When the session-start briefing shows unread inbox items, run /retorec-inbox to process them. The agent presents each item as a card, waits for your routing decision, writes the file, updates the list, and posts a confirmation back to the Telegram group.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  INBOX  [2 of 3] — velo
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  From:   Fadi
  When:   Today 09:32
  Type:   voice (transcribed)
  Class:  instruction

  "The checkout flow needs to support Apple Pay.
   Prioritise it — customers are asking for it."

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  What should I do with this?

  [1] operation/roadmap/backlog/
  [2] operation/knowledge/improvements/
  [3] operation/knowledge/product/
  [4] memory/fadi/
  [5] memory/mhd/
  [6] docs/
  [7] operation/incidents/
  [8] Custom path
  [9] Archive (no action)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After you choose, the agent writes the file and posts back to the Telegram group:

✓ Inbox item from Fadi (09:32) processed
→ Routed to operation/roadmap/backlog/apple-pay-2026-05-14.md

Hello World — Full Walkthrough

This section walks you through the entire system using a sample project called hello-memory. By the end you will have run a session, reviewed lessons, run synthesis, and approved a skill — one full loop.

mkdir -p ~/Retorec/projects/hello-memory/{.claude,scripts}
cd ~/Retorec/projects/hello-memory
git init
git config user.email "mohammad.binsabt@retorec.com"

echo 'PROJECT_NAME=hello-memory' > .claude/project.env

cp ~/Retorec/projects/velo/scripts/*.sh scripts/
chmod +x scripts/*.sh

export PROJECT_NAME="${PROJECT_NAME:-hello-memory}"

cat ~/.claude/settings.json

claude

You: explain how binary search works and write a Python example
Claude: [explains, writes code]
You: what are the limitations of binary search?
Claude: [answers]
You: how would you use this in a database lookup?
Claude: [answers]

bash scripts/review-lessons.sh

bash scripts/save-lesson.sh hello-memory \
  "Binary search only works on sorted data — always verify sort order before applying." \
  high global

bash scripts/memory-lessons.sh

node ~/Retorec/retorec-agent-os/memory/scripts/synthesize.js

bash scripts/review-skills.sh

Test Drive — Telegram Inbox

This walkthrough tests the full Telegram inbox flow end to end: bot receives a message, classifies it, saves it to SharePoint, posts a confirmation back to the group, and the session-start briefing surfaces it. Estimated time: 20–30 minutes (most of it is BotFather setup, which you only do once).

cd ~/Retorec/retorec-agent-os/tools/telegram-inbox
npm install

# Create a temporary .env with just your MS credentials
cp projects/.env.example projects/.env.hello-memory
# Fill in MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET, ANTHROPIC_API_KEY
# Leave the rest blank for now — we're just finding the site ID

node scripts/get-site-id.js

# projects/.env.hello-memory
PROJECT_NAME=hello-memory
TELEGRAM_BOT_TOKEN=7612345678:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHAT_ID=-1001234567890
MS_TENANT_ID=your-tenant-id
MS_CLIENT_ID=your-client-id
MS_CLIENT_SECRET=your-client-secret
SHAREPOINT_SITE_ID=your-site-id-from-step-4
ANTHROPIC_API_KEY=your-anthropic-key

npm run setup-list

Creating list: Retorec_ProjectInbox...
✓ List created: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  Adding column: Project... ✓
  Adding column: Sender... ✓
  Adding column: Timestamp... ✓
  ... (13 columns total)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Retorec_ProjectInbox is ready.
  All project bots will now write to this list.

cp projects/velo.config.json projects/hello-memory.config.json

npm install -g pm2   # skip if already installed
./deploy.sh

→ Project: hello-memory
  Starting new process...
  ✓ telegram-inbox-hello-memory running

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  All bots deployed. Run: pm2 list

pm2 logs telegram-inbox-hello-memory --lines 5

We should add a dark mode to the app. Users have been requesting it for months.

✓ Message received — classified as insight
Saved to inbox. Review it at your next session with /retorec-inbox

✓ Voice message received — classified as instruction
Saved to inbox. Review it at your next session with /retorec-inbox

[image] Caption: Competitor pricing page — reference for our own layout

✓ Image received — classified as insight
Saved to inbox. Review it at your next session with /retorec-inbox

!go Add a backlog item: implement dark mode toggle — high priority, requested by multiple users

⚡ !go executed
Added dark mode toggle to backlog — high priority user request

→ Written to ~/Retorec/projects/hello-memory/operation/roadmap/backlog/dark-mode-toggle-2026-05-14.md

cat ~/Retorec/projects/hello-memory/operation/roadmap/backlog/dark-mode-toggle-*.md

cd ~/Retorec/projects/hello-memory
claude

/retorec-session-start

INBOX
  3 unread Telegram messages — run /retorec-inbox to review

/retorec-inbox

API Endpoints Reference

Base URL: https://memory-api-fawn.vercel.app
All endpoints require: x-api-key: <RETOREC_API_KEY>

Shell Commands Reference

Troubleshooting

No lessons appear after a session

1. Confirm ~/.claude/settings.json has the hooks block with your correct username.
2. Confirm .claude/project.env exists in the project root with PROJECT_NAME set.
3. Confirm ~/Retorec/retorec-agent-os/.env has all required credentials (see below).
4. Run the hook manually to see errors:

   cd ~/Retorec/projects/hello-memory
   node ~/Retorec/retorec-agent-os/memory/scripts/extract-lessons.js

Required credentials by backend

SharePoint: "No lists found" or "site not found"

The SharePoint lists haven't been created yet. Run the one-time setup:

node ~/Retorec/retorec-agent-os/memory/scripts/setup-sharepoint.js

SharePoint: Graph API returns 401

M365_CLIENT_ID, M365_CLIENT_SECRET, or M365_TENANT_ID in ~/Retorec/retorec-agent-os/.env is wrong or missing. Verify the app registration in Azure AD has Sites.ReadWrite.All permission granted.

Sessions tagged as "unknown" project

PROJECT_NAME was not found. Check .claude/project.env exists and contains PROJECT_NAME=your-project-name.

Supabase API returns 401 Unauthorized

The RETOREC_API_KEY in ~/Retorec/retorec-agent-os/.env is wrong or missing. Check with Fadi.

SSH authentication fails on git push/pull

Make sure you're using github-retorec (not github.com) in your remote URL:

git remote set-url origin git@github-retorec:Retorec/repo-name.git

Synthesis fails with "CLAUDE_API_KEY not set"

Add CLAUDE_API_KEY=<your Anthropic key> to ~/Retorec/retorec-agent-os/.env.

Synthesis says "Not enough lessons — need at least 2"

SharePoint: Open Memory_Lessons, filter by Status = approved or active — fewer than 2 have been approved yet.
Supabase: Run review-lessons.sh or add manual ones with save-lesson.sh.

Scripts show wrong user email (personal instead of Retorec)

cd ~/Retorec/projects/your-project
git config user.email "mohammad.binsabt@retorec.com"

review-lessons.sh: "command not found: python3"

This script is Supabase-only. Install Python 3 if needed: brew install python3

show-profile.js: "No observations found"

No sessions have fired the profile hook yet for that email. Check two things:

1. Confirm git config user.email returns the correct Retorec email in the project directory.
2. Confirm the fourth hook (extract-person-observations.js) is present in ~/.claude/settings.json.

Run a real session (not a trivial one), wait 10 seconds, then try again.

show-profile.js: profile is very sparse

Fewer than 5 sessions have been observed. This is expected early on. Profiles improve significantly after 8–10 sessions. Short or purely lookup-based sessions produce no observations — sessions with back-and-forth decisions, design discussions, and problem-solving generate the richest data.

Person email is showing as "unknown"

The user_email field comes from git config user.email in the working directory. Set it correctly before starting a session:

git config user.email "fadi.jalajel@retorec.com"

Retorec Agent OS vs Claude Team / Enterprise

A common question: if we already have a Claude Team or Enterprise subscription, what does Retorec Agent OS add? The answer is that they operate at completely different layers — they are complementary, not competing.

What Claude Team / Enterprise Is

A subscription tier for the claude.ai web interface. It gives your team a better chat experience:

In short: a better web chat for a team. The intelligence is Claude the model. The workspace is claude.ai. That is the full scope.

What Retorec Agent OS Is

An execution operating system built on top of Claude Code (the CLI), not the web interface. It operates one layer deeper — closer to your file system, your git repo, your live projects:

The Five Real Differences

1. Memory
Claude Team remembers conversations within the web UI for that browser session. Retorec Agent OS writes structured memory files to git — cross-machine, cross-developer, compounding over time. Mohammad can pull the repo and instantly know what Fadi's Claude decided three weeks ago.

2. Agent Specialisation
Claude Team gives you one Claude per conversation. Retorec has 150+ agents, each pre-configured for a domain. When the task shifts from backend architecture to brand design, the right agent activates automatically — with the right rules already loaded.

3. Project Intelligence
Claude Team has no concept of a "project" beyond a folder of conversations. Retorec Agent OS knows the project's tech stack, methodology, current operational state, and every decision ever recorded — and loads all of it into the agent before it writes a single line.

4. Automation
Claude Team is fully manual: you open a conversation, you get a response. Retorec can run Telegram bots, session hooks, scheduled routines, and multi-step pipelines without a human initiating each step.

5. Compounding Intelligence
Claude Team starts fresh every session. Retorec's memory compounds — every session adds to what the agents know about your business, your decisions, and your standards. That accumulation is what Retorec calls Agentic DNA: intelligence that cannot be copied because it is built from your own history.

How the Layers Stack

┌─────────────────────────────────────────────────┐
│            Retorec Agent OS                     │  ← your operating system
│  agents · memory · projects · DNA               │
│  session protocols · Telegram · operation/      │
├─────────────────────────────────────────────────┤
│            Claude Code  (CLI)                   │  ← the engine
│  reads CLAUDE.md · executes tools · uses files  │
├─────────────────────────────────────────────────┤
│        Claude Pro / Max / API subscription      │  ← the model access layer
│          (what powers Claude Code)              │
└─────────────────────────────────────────────────┘

              (separate track)
┌─────────────────────────────────────────────────┐
│         Claude Team / Enterprise                │  ← web interface tier
│   shared conversations · SSO · admin controls  │
└─────────────────────────────────────────────────┘

When to Use Each

Retorec Agent OS v1.8  ·  May 2026  ·  Questions: fadi.jalajel@retorec.com