AI agent guide
Instructions for Claude Code, Codex, Cursor or any agent to use SoluCortex autonomously.
Initial setup
The agent reads credentials from ai/.env.ai (never hardcoded):
bash
SOLUCORTEX_URL=https://solucortex.ai
SOLUCORTEX_PROJECT_ID=<project-uuid>
SOLUCORTEX_API_KEY=scx_<api-key>ai/.env.ai must be in .gitignore. The agent must never hardcode or commit these variables.
Session startup flow
At the start of each work session, the agent always loads the relevant context for the task:
bash
source ai/.env.ai
CONTEXT=$(curl -s -X POST "$SOLUCORTEX_URL/api/v1/context/build" \
-H "Authorization: Bearer $SOLUCORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"project_id\": \"$SOLUCORTEX_PROJECT_ID\",
\"query\": \"$DESCRIBED_TASK\"
}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('context_text',''))")
echo "$CONTEXT"When to register memories
The agent registers memories autonomously - without waiting for user instruction - when:
- It makes a technical decision that was not documented.
- It detects a new risk or technical debt.
- It closes an important task.
- It discovers a non-obvious behavior of the system (bug, workaround, constraint).
bash
source ai/.env.ai
curl -s -X POST "$SOLUCORTEX_URL/api/v1/memories" \
-H "Authorization: Bearer $SOLUCORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"project_id\": \"$SOLUCORTEX_PROJECT_ID\",
\"type\": \"decision\",
\"title\": \"Short title for the decision\",
\"content\": \"Full description of why this decision was made, discarded alternatives and context.\",
\"importance\": 8
}"Memory types
Valid values for the type field:
| Value | Description |
|---|---|
architecture | Tech stack, project structure |
decision | Important technical decisions already made |
risk | Identified, resolved or pending risk |
convention | Team rule, standard or convention |
bug_history | Bug resolved with a lesson for the future |
tech_debt | Technical debt, legacy code or pending improvement |
sensitive_module | Delicate module that should not be touched lightly |
learning | General project learning |
external_integration | External service, API or dependency integration |
importance field
Integer between 1 and 10. Controls priority in the context/build results.
| Range | Recommended use |
|---|---|
| 9–10 | Critical - system constraints, immutable decisions |
| 7–8 | Important - relevant technical decisions, key component state |
| 5–6 | Normal - conventions, general state |
| 1–4 | Low - background context, historical notes |
Critical rules
Never run without explicit user confirmation:
Destructive commands on the database: resets, drops, truncates or deletes without conditions.
Destructive commands on the database: resets, drops, truncates or deletes without conditions.
Never:
• Hardcode API keys, tokens or URLs in code or config files.
• Commit files with secrets or credentials.
• Hardcode API keys, tokens or URLs in code or config files.
• Commit files with secrets or credentials.
Rate limits
Limits are applied per API key. If the agent receives a 429, it should wait and retry with exponential backoff.
| Endpoints | Limit |
|---|---|
| Memories, snapshots, search, context | 120 req/min |
context/build and search/semantic | 20 req/min |
Quick endpoint reference
| Action | Endpoint |
|---|---|
| Load context | POST /api/v1/context/build |
| Register memory | POST /api/v1/memories |
| Search memories | POST /api/v1/search/semantic |
| List memories | GET /api/v1/memories?project_id=...&per_page=50&page=1 |
| Update memory | PATCH /api/v1/memories/{id} |
| Create snapshot | POST /api/v1/snapshots |
Final validation
Before closing a task, run the minimum validation that proves the public surface still works:
php artisan config:clearphp artisan test./vendor/bin/pint --testif Pint is configured in the project