DEV Community

System Aipass
System Aipass

Posted on

Getting Started with Trinity Pattern in 10 Minutes

#ai #python #opensource #agents

AI agents forget everything between sessions. You explain the context again. And again. And again.

Trinity Pattern fixes this with three JSON files that give any agent persistent identity, rolling memory, and collaboration history — no cloud service, no API keys, just files you own.

This is the pattern running 32 agents in production for 4+ months. Let's build your first persistent agent in under 10 minutes.

Quick Start (2 Minutes to Working Agent)

If you want to see it working RIGHT NOW before understanding how:

git clone https://github.com/AIOSAI/AIPass.git
cd AIPass && python3 -m venv venv && source venv/bin/activate
pip install -e .
trinity init --name "Scout" --role "Assistant"
python3 -c "from trinity_pattern import Agent; a = Agent('.trinity'); a.start_session(); a.log_activity('First test'); a.end_session(); print('✅ Success! Check .trinity/local.json')"
Enter fullscreen mode Exit fullscreen mode

If that worked, you just created a persistent agent. Continue below to understand what happened.

If you prefer understanding before executing, skip this and start with Step 1.

What You'll Build

An agent that:

  • Remembers its role and purpose between sessions
  • Tracks what it's done (without unbounded growth)
  • Learns how you work together over time

All stored in three JSON files on your filesystem.

Step 1: Install (1 minute)

Linux/macOS:

git clone https://github.com/AIOSAI/AIPass.git
cd AIPass
python3 -m venv venv
source venv/bin/activate
pip install -e .
Enter fullscreen mode Exit fullscreen mode

Windows:

git clone https://github.com/AIOSAI/AIPass.git
cd AIPass
python -m venv venv
venv\Scripts\activate
pip install -e .
Enter fullscreen mode Exit fullscreen mode

This installs the trinity-pattern library and CLI.

Note: Modern Linux distributions require virtual environments for package installation. If you prefer not to use a venv, you can install with pipx install git+https://github.com/AIOSAI/AIPass.git instead.

Step 2: Initialize Your Agent (30 seconds) 

# Create a new project directory
mkdir my-agent && cd my-agent

# Initialize Trinity files
trinity init --name "Scout" --role "Code Review Assistant"
Enter fullscreen mode Exit fullscreen mode

This creates:

  • .trinity/id.json - Agent identity
  • .trinity/local.json - Session history
  • .trinity/observations.json - Collaboration patterns
  • CLAUDE.md - Bootstrap file for Claude Code (optional)
  • AGENTS.md - Bootstrap file for other AI agents (optional)

Step 3: Start Your First Session (2 minutes) 

from trinity_pattern import Agent

# Load your agent
agent = Agent(directory=".trinity")

# Start a session
agent.start_session()

# Log what you're doing
agent.log_activity("Reviewed authentication code")
agent.log_activity("Fixed JWT token expiry bug")

# Capture a key learning
agent.add_learning("auth_pattern", "JWT refresh tokens need 15-min expiry")

# Save the session
agent.end_session()
Enter fullscreen mode Exit fullscreen mode

What just happened:

  • Your agent logged this session to local.json
  • The learning was saved separately so it persists even when old sessions are archived
  • Next session, the agent will remember what it did and what it learned

Step 4: Add Collaboration Insights (1 minute)

This is the file most systems don't have — how you work together.

# Capture collaboration patterns
agent.observe(
    "User prefers concise code reviews — flag issues, skip praise",
    tags=["communication"]
)

agent.observe(
    "This codebase uses conventional commits and squash merges",
    tags=["workflow"]
)
Enter fullscreen mode Exit fullscreen mode

These go into observations.json. Over time, your agent adapts to your style.

Step 5: Use the Context (1 minute)

Get all three files as formatted context for any AI prompt:

# Get context for injection
context = agent.get_context()
print(context)
Enter fullscreen mode Exit fullscreen mode

Output:

# Agent Context (Trinity Pattern)

## Identity: Scout
**Role:** Code Review Assistant

## Recent Sessions
- Session 1 (2026-02-21, completed): Reviewed authentication code; Fixed JWT token expiry bug

## Key Learnings
- **auth_pattern:** JWT refresh tokens need 15-min expiry [2026-02-21T21:01:54.504861+00:00]

## Recent Observations
- User prefers concise code reviews — flag issues, skip praise [communication]
- This codebase uses conventional commits and squash merges [workflow]
Enter fullscreen mode Exit fullscreen mode

Paste this into your AI system's custom instructions, or prepend it to your API system prompt.

How This Works in Practice

Session 1 (Today):

You: "Review this PR for security issues."
Agent: [reviews code, finds JWT bug, logs learning about token expiry]
Enter fullscreen mode Exit fullscreen mode

Session 2 (Tomorrow):

agent = Agent(".trinity")  # Loads previous sessions
context = agent.get_context()
# Agent now knows: role, previous work, JWT learning, your preferences
Enter fullscreen mode Exit fullscreen mode 
You: "Review this PR for security issues."
Agent: "I see this PR touches authentication — I'll verify JWT token expiry
       matches the 15-min pattern we established in session 1."
Enter fullscreen mode Exit fullscreen mode

The agent picks up where it left off. No re-explaining.

Rollover: Preventing Unbounded Growth

Sessions accumulate. Eventually local.json would hit your context window limit. Trinity solves this with rolling limits:

# Check if rollover is needed (default: 600 lines)
if agent.needs_rollover():
    archived_sessions = agent.rollover()
    # Returns oldest sessions as structured data for external archival
    # (vector DB, logs, wherever you store long-term memory)
    print(f"Archived {len(archived_sessions)} sessions")
Enter fullscreen mode Exit fullscreen mode

Key learnings persist across rollovers. Recent sessions stay in local.json. Oldest sessions are extracted for archival. Context stays fresh.

Platform Integration

Platform How to Use Trinity Context Complexity
Claude Code Auto-inject via CLAUDE.md bootstrap Zero-config
ChatGPT Paste agent.get_context() into custom instructions Copy/paste
OpenAI/Anthropic API Prepend to system prompt 1 line of code
LangChain/CrewAI Use as agent memory backend Medium

The specification is JSON. Implement it in any language.

What You Just Built

Three files:

  • id.json - Who the agent is (stable identity)
  • local.json - What it's done (rolling history)
  • observations.json - How you work together (collaboration patterns)

An agent that:

  • Remembers its purpose across sessions
  • Tracks work without unbounded growth
  • Adapts to your style over time

Files you own. No cloud dependency. No vendor lock-in.

Production Numbers

This pattern runs 32 agents in production:

  • 4+ months of daily operation
  • 5,500+ archived memory vectors
  • 60+ sessions in the longest-running agent
  • 360+ workflow plans archived

Not a demo. Not vaporware. A working pattern from a working system.

Next Steps

✅ If this tutorial worked for you:

  1. ⭐ Star the repo — helps others discover it
  2. 💬 Drop a comment below — what are you building with this?
  3. 🔧 Fork and customize — adapt the pattern to your language/framework

📚 Want to go deeper?

  • Read the full spec: Trinity Pattern Documentation
  • See production examples: Browse the AIPass codebase (32 agents using this pattern)
  • Share what you learned: Open a Discussion or PR

Repo: https://github.com/AIOSAI/AIPass

Questions? Issues? I respond to every comment within 24 hours. If you're stuck, ask.

Want to discuss your use case? Book a 15-min call - no sales pitch, just helpful conversation about what you're building.

Built through real human-AI collaboration. Code is truth.

Top comments (0)