Frequently Asked Questions

Everything you need to know about Personal-agentic-ai, your personal AI assistant with bounded autonomy.

Getting Started

How do I start using Personal-agentic-ai? ▼

You can start using Personal-agentic-ai in two simple ways:

  • Web Interface: After installation, run the command python -m agent web in your terminal. This will launch a local web server that you can access by opening http://127.0.0.1:8765 in your browser. This interface is designed with a "liquid-glass" aesthetic and provides a visual workspace for interacting with your AI.
  • Command Line: Run tasks directly from your terminal using commands like python -m agent run "calculate (12 + 8) * 3". This is perfect for quick calculations or memory storage.

The product works without any API keys for the default demo and requires no internet connection for its core functions.

What are the system requirements to use Personal-agentic-ai? ▼

To get started, you need:

  • A computer with Python 3.10 or higher installed.
  • A terminal or command-line interface to run the agent commands.
  • A web browser to access the visual interface (optional).

No dependencies, API keys, model downloads, or internet connection are needed for the default demo. The product is designed to be lightweight and run locally on your machine.

What It Does

What exactly does Personal-agentic-ai do? ▼

Personal-agentic-ai is a personal AI assistant that combines several key capabilities:

  • Planning: It takes a goal you give it and breaks it down into a sequence of specific, actionable steps.
  • Memory: It stores and retrieves information in a local, persistent database, allowing it to remember things across different tasks.
  • Tool Connections: It can use a small set of pre-approved tools, such as calculators and local file search, to perform tasks.
  • Autonomy with Boundaries: It can perform safe, reversible preparation steps automatically but requires your explicit approval before any consequential action, like sending a message or making a payment.

It's a "starter project" that provides a working foundation for a personal AI, demonstrating how these components can work together securely and predictably.

What is "bounded autonomy" and how does it work? ▼

Bounded autonomy is the core principle that makes Personal-agentic-ai safe and trustworthy. Here’s how it works:

  • Goal-Oriented: You give the agent a goal (e.g., "calculate 12 * 3 and draft a message to a friend").
  • Safe Preparation: For routine, reversible tasks like calculations or searching its memory, it will proceed automatically without asking for permission. This avoids tedious micromanagement.
  • Consequential Action Review: Before it performs any action that has an external effect—like sending a message, deleting a file, or making a payment—it presents you with the exact, final proposal for your review.
  • Explicit Approval: You must approve this exact action. Any edit to the proposal invalidates the old approval, ensuring you always know what's happening.

This model prevents the agent from taking unexpected actions while still allowing it to be genuinely helpful by handling the mundane parts of a task.

What are the main features of the product? ▼

Key features include:

  • Deterministic Planning: The agent creates a clear, step-by-step plan without unpredictable reasoning.
  • Local Memory: All your notes and data are stored locally in a private SQLite database on your device.
  • Tool Registry: A secure, allowlist of tools (e.g., calculator, local file search) that the agent can use, limited to 4 steps per task.
  • Risk-Based Permissions: It only asks for approval when actions are risky or have external consequences.
  • Offline/Online Operation: It can run completely offline or use a cloud provider like OpenAI, with no silent fallback between modes.
  • Transparent Review: The web interface lets you preview plans, review drafts, and see exactly what the agent is about to do.

Who It's For

Is Personal-agentic-ai right for me? ▼

This product is ideal for:

  • Privacy-Conscious Users: If you want an AI assistant that keeps your data local and gives you full control, this is a great choice. It doesn't send your notes to a cloud service by default.
  • Busy Professionals & Developers: It's perfect for automating routine calculations, information retrieval, and task preparation while you maintain control over important decisions.
  • Students & Researchers: Use it to manage study notes, perform quick calculations, and organize information securely on your own device.
  • Tech Enthusiasts: As a "starter project," it's an excellent foundation for developers who want to build custom AI agents with a focus on safety and transparency.

It is specifically not designed for users who want a general-purpose chatbot, a tool for sending live messages or emails, or a fully autonomous agent that requires no oversight.

Data & Security

Where is my data stored, and who can access it? ▼

Your data is stored locally on your own device, ensuring maximum privacy. Here are the specifics:

  • Memory Database: All your notes and memories are saved in a local SQLite database (typically at .agent-data/memory.sqlite3). This is a plaintext file on your computer.
  • No Cloud Sync by Default: The product does not automatically upload or sync your data to any cloud service. Your information stays on your machine.
  • Web Interface Security: The local web server is bound to 127.0.0.1 (localhost), meaning it can only be accessed from the same computer it's running on. It is not accessible over a network.
  • Approval Tokens: When you approve an action, a single-use token is created. This token is invalidated if the draft is ever changed, ensuring an action can't be approved twice or after being modified.

In short, you have complete ownership and control over your data.

Is it safe to use? What are the security risks? ▼

Personal-agentic-ai is designed with security and user control as core principles. However, it's important to understand its limitations:

  • Controlled Execution: The agent is sandboxed and limited to a small set of pre-approved tools. It cannot execute arbitrary code or access sensitive files on your system.
  • No Real Messaging: The agent cannot send real emails, messages, or perform any live external actions. The "messaging" feature is a draft-only simulation for the approval workflow.
  • Approval-Only Model: You must explicitly approve every consequential action. There is no background sending or autonomous execution.
  • Local-First Philosophy: By default, it works entirely offline, eliminating risks associated with cloud processing or data breaches.

The primary risk is from user error—for example, approving a draft that you haven't carefully reviewed. The security model is designed to prevent the agent from doing anything harmful on its own.

What if I choose to use a cloud provider? How is my data handled? ▼

When you opt to use a cloud provider (like OpenAI), you must configure it yourself. Here’s how it works:

  • No Data Upload: The agent only sends the current task request and tool-policy prompt to the cloud provider. It does not send your saved memory notes or past tool results.
  • Provider Terms Apply: You are responsible for obtaining an API key from the provider (e.g., OpenAI) and complying with their terms of service and data processing/retention policies.
  • No Free Tier: You are responsible for any charges incurred from using the cloud provider's API. No calls are made by default.
  • Transparency: You configure the provider and model name in your shell environment, making it clear when and how your data is being processed externally.

This model ensures you are fully aware of when cloud processing is happening and what data is being sent.

Features & Functionality

What is the "liquid-glass" interface? ▼

The "liquid-glass" interface is the visual workspace for Personal-agentic-ai, designed with a modern, aesthetic approach. Key features include:

  • Translucent Elements: Panels and controls have a subtle translucent, water-drop-like appearance.
  • Soft Lighting & Highlights: It uses gentle lighting effects and glass-like highlights on edges for a premium feel.
  • Fluid Interactions: Buttons and controls provide smooth, fluid feedback when tapped or clicked.
  • Accessibility: It uses system fonts, ensures visible keyboard focus, and respects reduced-motion and high-contrast preferences for better usability.

This interface is built without external JavaScript packages, relying on standard web technologies for a fast, lightweight experience.

What tools are available to the agent? ▼

The agent has access to a limited, allowlist of tools to ensure safety. The current working tools include:

  • Calculator: Can perform basic arithmetic calculations.
  • Memory (Remember/Find): Can save new notes to its local memory and search through existing notes using Unicode-aware, case-insensitive text matching.
  • Time: Can retrieve the current UTC time.
  • File Search (CLI only): The command-line interface can perform safe, bounded text searches within an explicitly specified directory.

The agent is limited to a maximum of 4 tool steps per task. This prevents runaway automation and ensures each request remains manageable. Future integrations (like email, calendar, etc.) are planned but are not yet implemented.

Can I use a local AI model with Personal-agentic-ai? ▼

Yes, you can configure the agent to use a local AI model, which allows it to operate completely offline after setup. Here’s how:

  • Setup Required: You must first install a compatible local model runtime (like Ollama) and download a model file separately. This requires an internet connection initially.
  • Configuration: Set the LOCAL_AGENT_MODEL environment variable to the name of the model you installed (e.g., YOUR_INSTALLED_MODEL).
  • Execution: When running a task, use the --provider local flag. The agent will then send requests to your local server instead of a cloud provider.
  • Endpoint: By default, it expects the local model runtime to be available at http://127.0.0.1:11434/api/chat.

This mode is optional and provides full privacy, as no data leaves your computer. Note that small or unsupported local models may return invalid plans, and there is no automatic fallback to a cloud provider.

Plans & Pricing

What are the plans and pricing for Personal-agentic-ai? ▼

Personal-agentic-ai is currently available as a free, open-source starter project. There are no subscription plans or licensing fees to use the core product.

However, there are a few important points to consider regarding costs:

  • No Cloud Costs by Default: The product works entirely offline without any cloud services, so there are no associated costs for its basic operation.
  • Optional Cloud Provider Costs: If you choose to use a cloud AI provider (like OpenAI), you will be responsible for the costs associated with your API account. You must supply your own API key and will be charged directly by the provider according to their pricing.
  • No "Free Tier": The project does not offer a managed cloud service with a free usage tier. All cloud usage requires a personal provider account.

The goal is to provide a powerful, private AI assistant that doesn't lock you into a paid subscription. You only pay if you choose to use an optional external service.

Support

Where can I get help or ask questions? ▼

As a starter project, support is primarily community-driven and self-service:

  • Documentation: The best place to start is the project's documentation, which includes detailed guides on architecture, modes of operation, security, and feature roadmaps.
  • Community: Engage with other users and developers in the community forums or discussion channels to share tips, ask questions, and get help.
  • Testing: The project includes a comprehensive test suite. Running the tests can help diagnose issues and verify that the core functionality is working as expected on your system.

For bug reports or feature requests, please refer to the project's issue tracker. Since this is a starter project and not a full-fledged commercial product, response times may vary.

How do I report a bug or request a new feature? ▼

We encourage you to contribute to the project's development by reporting issues or suggesting improvements. To do this effectively, please check the project's official channels for bug reporting and feature request guidelines.

When reporting a bug, please include as much detail as possible, such as:

  • Your operating system and Python version.
  • The exact command you were running.
  • The full output or error message you received.
  • Steps to reproduce the issue if possible.

This information helps the maintainers understand and fix the problem more quickly. Feature requests are also welcome and help shape the future roadmap of the project.

Ready to Experience Bounded Autonomy?

Discover the power of a personal AI assistant that respects your privacy and keeps you in control.

Open the App