🌌 Sams : The Personal Agent OS & Marketing Framework

Sams is a modular, high-fidelity Personal Agent architecture designed to bridge the gap between LLM reasoning and local system execution. It combines an adversarial AutoReason marketing engine with a sandboxed Agent OS foundation.

---

✨ Features

• 🧠 Adversarial Optimization (AutoReason): A Karpathy-style loop that uses Critic and Judge agents to iteratively refine marketing copy until it survives blind evaluation.
• 🛡️ Docker-Sandboxed CLI: Safely execute shell commands and file operations within isolated Ubuntu containers.
• 📂 MCP (Model Context Protocol): Ready for external tool synchronization via standard JSON-RPC.
• 💾 Multi-Layer Memory:
  • Global Persona: Core identity stored in ~/.sams/soul.md.
  • User Preferences: Persistent settings in ~/.sams/user.md.
  • Local Discovery: Automatic ingestion of SAMS.md or CLAUDE.md context files.
• 🚀 Swarm Coordination: Logic for spawning specialized sub-agent teams for complex, multi-stage engineering tasks.

---

🔥 Core Capabilities

Capability	Description
Autonomous ReAct Loop	Sams doesn't just talk; it reasons and acts. It iteratively uses tools, processes results, and refines its approach until the goal is met.
The Hard Wall (Sandbox)	Executes all terminal commands inside a Docker Sandbox (ubuntu:latest), protecting your host OS from accidental damage or malicious code.
Context-Aware Memory	Merges global persona (soul.md), user preferences (user.md), and local project overrides (SAMS.md) into a high-fidelity system prompt.
Dynamic Tool Registry	Easily extensible tool system featuring Pydantic schemas for built-ins, Shell, and MCP-synced tools.
Event-Driven Messaging	A decoupled MessageBus architecture ready to bridge the engine to Slack, Telegram, or custom webhooks.

---

🚀 Real-World Use Cases

• 👨‍💻 Autonomous Software Engineering: Ask Sams to read your codebase, identify bottlenecks, and write/test new modules safely within the sandbox.
• 🛡️ Safe System Investigation: Run complex bash scripts or audit your system files without giving an LLM direct access to your root file system.
• 📈 Adversarial Marketing Optimization: Use the built-in AutoReason framework to generate high-converting copy that survives ruthless peer-critique from other agents.
• 📂 Standardized Project Guardrails: Drop a SAMS.md file into a repository to instantly enforce specific coding standards or library choices across all agent interactions.
• 🤖 Cross-Platform Virtual Assistant: Deploy the Sams backend and interact with your local environment via secure Slack or Discord channels.

---

🛠 Installation & Setup

1. Clone & Environment:

   git clone https://github.com/your-repo/sams.git
   cd sams
   python3 -m venv .sams-env
   source .sams-env/bin/activate
   pip install -e ./sams

2. Configure API Key: Create a .env file in the root directory:

   GOOGLE_API_KEY=your_gemini_api_key_here

3. Initialize Sams:

   s setup

---

📈 Showcase: AutoReason Optimization

The AutoReason engine treats content generation as an optimization problem. Below is an example of the system iterating on LinkedIn hooks until they meet the brand's quality threshold.

📥 Example Input

python main.py --goal "Generate 5 LinkedIn hooks for Sams" --platform "LinkedIn" --draft "Sams is a personal agent on your terminal."

📤 Optimized Output

Tip

After 3 rounds of adversarial critique, the system produced the following "Champion" variants:

Hook Type	Refined Copy
The Bottleneck	"The real bottleneck to your biggest wins? It's often your tools. Stop letting tech hold you back. Sams isn't an app; it's an engine."
Precision	"Information overload kills clarity. While your peers drown in data, navigate every challenge with absolute precision."
Revolution	"Still managing your day like it's 2010? Outdated processes are holding you back. Step into the intelligent revolution."

---

🏗 Architecture

Sams is built on a distributed agentic design:

graph TD
    User([User CLI]) --> Gateway[Session Pool / Gateway]
    Gateway --> Engine[QueryEngine / Agent Loop]
    Engine --> Memory[Soul + User + Local MD Context]
    Engine --> Tools[Registry: File I/O, MCP, Sandbox]
    Tools --> Sandbox[Docker Ubuntu Container]
    Engine --> LLM[Gemini 1.5 Flash Provider]

Loading

---

🤝 Contributing

Contributions are welcome! Whether it's adding a new LLM Provider or a Built-in Tool, please feel free to open a PR.

---

Built with ❤️ by the Simranjeet Singh