Documentation

Everything you need to install, configure, and operate SOAGILA across VS Code, Cursor, Windsurf, the Desktop app, and browser extensions.

On this page

Quick start — 5 minutes

  1. Create your account at soagila.ai/register.
  2. Open the Download page at dashboard/download. Three cards, one per client.
  3. Install the VS Code extension via the Marketplace link. It activates automatically when you open any project folder.
  4. Click “One-click Sign In” on each client card — the deep link hands your access token to the client without you having to type a password.
  5. Start working with Claude Code as normal. SOAGILA remembers architectural decisions, bug fixes, and configuration changes in the background. You never have to callsoagila_remember manually.

Install the clients

VS Code / Cursor / Windsurf
Install from the Marketplace or drop in a .vsix. The extension auto-detects the IDE flavour and tags telemetry accordingly.
Marketplace →
Desktop app
Windows installer (NSIS or MSI). Once installed, launch from the Start Menu, sign in, and the app syncs to the daemon in the background.
Download .exe →
Browser extension
Captures context from claude.ai, chat.openai.com, and gemini.google.com. Auto-recall + auto-remember, no manual setup after install.
Chrome Web Store →
SOAGILA Daemon
A tiny background service (14 MB, Python-powered) that VS Code + Desktop + Browser all talk to. Auto-starts at login, runs under your user account, no admin rights needed. Only install this if you want the zero-friction install flow the docs describe — otherwise each client falls back to legacy per-process mode.
Download .zip →

Write your first memory

The fastest way to confirm SOAGILA is working: open Claude Code in any project, tell it about a decision (“we're using PostgreSQL”), and wait. Within a few seconds Claude should call soagila_remember automatically. Verify with:

# From VS Code's command palette:
Ctrl+Shift+P → SOAGILA: Show Status

# Or check disk directly (advanced):
ls ~/.soagila/projects/*/soagila.db

If memory count isn't going up, see Troubleshooting.

Context persistence (auto-snapshot)

Anthropic's Claude Code automatically compacts long conversations to save tokens. Compaction is lossy — fine-grained details disappear. SOAGILA solves this with two mechanisms:

  • Automatic hook: a .claude/hooks.json entry fires on every user prompt. When the token count crosses a threshold (default 120k), the hook POSTs a full transcript snapshot to the daemon. No Claude insight required.
  • Manual tools: soagila_snapshot and soagila_restore are available as explicit MCP tools. Claude can call them when it notices the conversation is getting long. After compaction, it calls soagila_restore as its first action to replay the captured state.

The hook is installed automatically the first time you open a project after the v0.8.0 extension update. You can disable it with soagila.hooks.autoInstall: false in VS Code settings.

Troubleshooting

Q: VS Code says 'SOAGILA MCP server not connected'
Two common causes: (1) the Python 3.10+ runtime is missing or wrong version — set soagila.pythonPath explicitly; (2) the daemon is running but the extension is in legacy mode — run 'SOAGILA: Restart MCP Server' from the command palette.
Q: Memory count isn't going up
Claude may be ignoring the CLAUDE.md rules. Open the Claude chat and say 'Please load SOAGILA tools via ToolSearch, then call soagila_status'. If status shows 19 → 19, confirm the hook is installed (.claude/hooks.json exists).
Q: 'database is locked' errors in logs
You're running the legacy per-process mode with multiple VS Code windows open on the same project. Install the SOAGILA Daemon (see Install the clients) so all windows share one writer.
Q: Dashboard shows 0 memories but local has hundreds
Cloud sync is Pro+ only. Free tier stores memories locally on your machine (encrypted), but doesn't push them to soagila.ai. Upgrade to Pro from the Subscription page to enable sync.
Q: I want to delete everything (GDPR)
Settings → Danger Zone → Delete Account. You'll receive an email confirmation link. Clicking it triggers crypto-shredding — the master key is destroyed, making the data mathematically unrecoverable.

API reference (Pro+)

Direct HTTP access to your own memories is available on Pro and Enterprise tiers. Base URL: https://api.soagila.com. Authentication: Authorization: Bearer <access_token>.

Common endpoints:

GET   /sync/status           # memory counts + quota
POST  /tools/remember        # store a memory
POST  /tools/recall          # search memories
POST  /tools/snapshot        # pre-compaction snapshot
POST  /tools/restore         # recover a snapshot
GET   /user/profile          # current user + devices
GET   /api/health            # public health check

Full OpenAPI schema at api.soagila.com/openapi.json (coming in v1.1).

Security & privacy

  • AES-256-GCM encryption at rest with per-memory keys wrapped by a per-project master key derived via PBKDF2-SHA256 (480k iterations) from machine ID + project hash + random salt.
  • OS credential store integration — the master salt lives in Windows Credential Manager / macOS Keychain / Linux Secret Service, not in a plain file.
  • Per-project isolation— each workspace has its own SQLite database and its own master key. Project A's secrets cannot leak into project B.
  • End-to-end encrypted cloud sync — the server stores ciphertext blobs only. We cannot read your memories even with full database access.
  • GDPR Article 17 right to erasure — two-step deletion with email verification and cryptographic shredding.

Support

For help email info@soagila.ai. Response within 24 hours for Pro, within 4 hours for Enterprise.

For bug reports, open an issue at github.com/sonatciftcioglu/soagila (coming soon).