Developers are increasingly granting AI agents direct access to their local terminals and file systems to automate complex coding tasks. This shift toward agentic workflows with tools like Claude Code and Cursor has introduced a critical vulnerability where an agent might accidentally print an API key to the console or read a .env file into its context window. The risk is no longer just about remote exploits but about locally exposed agent keys that can be leaked through the very logs meant to debug the agent's progress.

The Architecture of Secret Isolation

To mitigate these risks, key-amnesia introduces a specialized security layer designed to decouple sensitive credentials from the AI agent's immediate reach. The tool is installed via the Python package manager using the following command:

pip install key-amnesia

At its core, key-amnesia functions as an encrypted vault. Rather than storing keys in plain text files that an agent can easily read, it utilizes Argon2id for secure password hashing and SecretBox for authenticated encryption. The master password required to unlock this vault is never stored on disk and is entered exclusively via the user's keyboard. Once unlocked, the tool does not simply dump all keys into the global environment. Instead, it uses a specific execution wrapper:

ka run <command>

When a process is started via `ka run`, the tool injects the necessary secrets into the environment variables of that specific child process only. This ensures that the keys exist only in the volatile memory of the executing task and not in the persistent environment of the AI agent itself. For developers using AI-powered code editors, key-amnesia provides dedicated safe hooks for Claude Code, Cursor, and Codex, allowing these tools to interact with protected resources without ever seeing the raw credentials.

Redefining the Trust Boundary

The fundamental difference between key-amnesia and standard environment variable management is the active censorship of the output stream. In a typical setup, if an agent runs a command that happens to print a secret to the terminal, that secret is fed back into the agent's prompt, potentially leaking it into the LLM's history or external logs. key-amnesia intercepts the command results and scrubs any identified secrets before the agent can read them. This creates a one-way valve where the process can use the key, but the agent cannot see it.

To handle the tension between security and developer velocity, the tool offers two distinct operational modes. The per-call mode is the most restrictive, requiring the user to enter their password every single time a secret is accessed. For more fluid workflows, the cached mode allows the vault to remain open for 30 minutes, eliminating the need for repetitive password entry.

Another critical security feature is the isolation of the approval process. When an agent requests an action that requires authorization, key-amnesia triggers a separate console window. This window is completely isolated from the agent's read capabilities, meaning the AI cannot trick the user or manipulate the approval prompt. While the tool currently supports Windows and Linux, macOS support remains in an experimental phase. Users should note that certain edge cases exist, such as the ability to bypass censorship by encoding secrets in the output, and the fact that the tool denies approvals in headless environments to prevent unauthorized remote access.

This approach transforms the AI agent from a privileged user with full access to a restricted operator that must request temporary, monitored access to sensitive data.