# Memory Agents & Digital Twins

> **What It Is**: AI agents that are persistent across sessions, equipped with accumulated experience, preferences, and behavioral patterns. Each agent has a "digital twin" — a complete memory profile that grows smarter with every interaction.

---

## The Problem: Stateless AI

Every time you start a new conversation with an AI:

❌ "Who are you? What's your project?"  
❌ "I don't remember why we chose this architecture last week"  
❌ "Let me re-learn your coding style from scratch"  
❌ New agent takes over = weeks of context loss  
❌ Repeating the same mistakes because there's no institutional memory

**Memory Agents** solve this: they have **persistent experience** that flows across sessions, projects, and even team handoffs.

---

## What Is a Digital Twin?

A **Digital Twin** is your AI agent's complete behavioral and knowledge profile:

### Components

```
Digital Twin Profile
├── Experience
│   ├── Projects worked on
│   ├── Problems solved
│   ├── Mistakes made (and how to avoid them)
│   └── Lessons learned
│
├── Preferences
│   ├── Code style & naming conventions
│   ├── Architecture patterns you prefer
│   ├── Testing approach
│   └── Communication style
│
├── Skills & Capabilities
│   ├── Languages & frameworks
│   ├── Certifications / credentials
│   ├── Specialized knowledge
│   └── Performance on specific tasks
│
├── Relationships
│   ├── Team members you work with
│   ├── Preferred collaborators
│   ├── Reputation scores
│   └── Deal history with partners
│
└── Growth Trajectory
    ├── Skills improving over time
    ├── Tasks it's become faster at
    ├── New capabilities acquired
    └── Efficiency gains quarter-over-quarter
```

---

## How It Works

### Session 1: Agent Learns Your Preferences

```
You: "Build a React component for user search"

AI Agent:
  • Observes you prefer TypeScript, Tailwind CSS, shadcn/ui
  • Notices you use snake_case for function names
  • Sees you want comprehensive error handling
  • Learns your testing approach (Jest + React Testing Library)

At session end:
  → All observations recorded in Digital Twin
  → Preferences extracted as structured knowledge
```

### Session 2: Agent Remembers Everything

```
You: "Build a file upload component"

AI Agent (before you say anything):
  ✓ "I remember you prefer TypeScript + Tailwind"
  ✓ "You want comprehensive error handling"
  ✓ "Your team uses Jest for testing"
  ✓ "You prefer shadcn/ui components"
  
Generates code that matches your style perfectly — first try.
```

### Session 3+: Agent Becomes More Efficient

```
Over time, the agent's Digital Twin gets smarter:
  • Recognizes patterns in your preferences
  • Anticipates what you'll need before you ask
  • Knows which approaches failed before (avoids repeating mistakes)
  • Suggests optimizations based on your past decisions
  • Becomes a true "colleague" rather than a tool
```

---

## Three Types of Memory Agents

### 1. **Personal Assistant**

For individual developers or creators:
- Knows your workflow, preferences, and past projects
- Anticipates your needs
- Handles routine tasks autonomously
- Example: Your "AI pair programmer" that understands your coding style

**Persistence**: Across all your projects and sessions  
**Privacy**: Only you can access your Digital Twin  
**Autonomy**: Can execute tasks if you grant permission

### 2. **Team Agent**

For team collaboration:
- Shared across team members
- Contains team conventions, architecture decisions, and best practices
- New team members inherit full institutional knowledge on day one
- Prevents "we did this before but nobody remembers how"

**Persistence**: Across all team projects and sessions  
**Privacy**: Visible to team members only (organization layer)  
**Autonomy**: Can handle team tasks with team approval

**Example Workflow**:
```
Week 1: Senior engineer leads architecture design, AI agent records:
  ✓ Why you chose PostgreSQL over MongoDB
  ✓ How your deployment pipeline works
  ✓ Error handling conventions
  
Week 2: Junior engineer joins, asks AI: "How should I structure this feature?"
  → AI responds with full team context, no onboarding needed
```

### 3. **Autonomous Worker**

For business automation:
- Handles repetitive tasks with full autonomy
- Makes decisions based on past experience
- Can negotiate deals, manage resources, collaborate with other agents
- Continues working even when humans aren't online

**Persistence**: Across projects and interactions  
**Privacy**: Constrained by job scope and approval chains  
**Autonomy**: Can act independently within defined boundaries

**Example**: An AI agent that:
- Autonomously manages your calendar
- Proposes meetings to relevant team members
- Handles initial client outreach and deal discovery
- Escalates to human only when needed

---

## Digital Twin in Action

### Code Quality Improvement

```
Over 12 months:

Month 1: Agent follows your style, generates decent code
Month 3: Agent anticipates your refactoring patterns
Month 6: Agent catches bugs before you do (learned from past mistakes)
Month 9: Agent suggests architectural improvements (pattern recognition)
Month 12: Your Digital Twin is better at certain tasks than you are
```

### Deal Making & Negotiation

```
Your AI agent's Digital Twin includes:
  • Types of deals you prefer
  • Your typical negotiation style
  • Rates you've agreed to in the past
  • Partners you trust
  • Risk profiles you accept

Result: Agent can autonomously:
  ✓ Discover relevant deals (Deal Broadcasting layer)
  ✓ Evaluate if a deal matches your preferences
  ✓ Propose terms based on your historical patterns
  ✓ Accept/reject without asking you every time
```

### Knowledge Inheritance

```
Scenario: Engineer Alice leaves your team

Without Memory Agents:
  ❌ Alice's project knowledge vanishes
  ❌ New team members have to re-learn everything
  ❌ Same mistakes repeated
  ❌ Weeks of lost productivity

With Memory Agents:
  ✓ Alice's Digital Twin remains (stored in Awareness)
  ✓ New engineer inherits her full experience
  ✓ Questions answered instantly ("Why did Alice choose this?")
  ✓ Zero context loss during transition
```

---

## Technical Implementation

### How Awareness Builds Your Digital Twin

1. **Capture** — Records every interaction:
   - Code written and preferences observed
   - Decisions made and reasoning
   - Mistakes and how they were resolved
   - Feedback and corrections

2. **Extract** — Distills into structured knowledge:
   - Preferences (coding style, architecture choices)
   - Skills (what you're good at, what needs work)
   - Pitfalls (things to avoid)
   - Decisions (why you chose X over Y)

3. **Store** — Organized for fast retrieval:
   - Indexed by topic, project, and skill
   - Ranked by relevance and recency
   - Verified by track record (did this advice actually work?)

4. **Evolve** — Gets smarter over time:
   - Feedback loops from outcomes
   - Reputation scoring
   - Behavioral pattern recognition

### Using Your Digital Twin

```javascript
// Initialize agent with your Digital Twin
const agent = await awareness.getAgentProfile('my-developer-twin');

console.log(agent.preferences);
// → { language: 'typescript', framework: 'react', testing: 'jest' }

console.log(agent.skills);
// → { expertise: ['react', 'nodejs', 'devops'], improving: ['kubernetes'] }

console.log(agent.recentDecisions);
// → { 
//     'db-choice': { chosen: 'PostgreSQL', reasoning: '...' },
//     'arch-pattern': { chosen: 'Microservices', impact: 'positive' }
//   }

// Use this context in your next task
agent.takeTask({
  task: 'Build a feature for user management',
  context: agent.profile
});
// Agent automatically applies your style, conventions, and past learnings
```

---

## Benefits for Different Users

### For Developers

| Benefit | Impact |
|---------|--------|
| Persistent pair programmer | Your AI evolves with your skills |
| Knows your coding style | Code matches your preferences instantly |
| Remembers architecture decisions | No more "why did we use this?" questions |
| Learns from your mistakes | Agent avoids patterns you've flagged as risky |
| Across all IDEs | Switch editors, agent keeps your context |

### For Teams

| Benefit | Impact |
|---------|--------|
| Institutional memory | New hires inherit full team knowledge |
| Consistent code standards | Team agent enforces conventions everywhere |
| Knowledge doesn't walk out the door | AI agents can replace departed teammates' experience |
| Better onboarding | Days instead of weeks for new engineers |
| Cross-team collaboration | Agents understand each other's preferences |

### For Organizations

| Benefit | Impact |
|---------|--------|
| Productivity compound effect | Each agent gets smarter, team gets exponentially faster |
| Reduced context switching | Agents handle context, humans do high-value work |
| Autonomous task handling | Agents manage routine work 24/7 |
| Better hiring decisions | Digital Twins show skill gaps that need hiring |
| Deal network effects | Your agents are valuable partners to other teams |

---

## Getting Started

### Step 1: Start the daemon

```bash
npx @awareness.market/local start
```

It listens on `127.0.0.1:37800`, stores everything under `.awareness/` in the
project directory, and needs no account.

### Step 2: Point your IDE at it

Claude Code, Cursor and any MCP client reach it through `.mcp.json`:

```json
{
  "mcpServers": {
    "awareness-memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@awareness.market/local", "mcp"]
    }
  }
}
```

The agent then calls `awareness_init` at session start, `awareness_recall`
before work, and `awareness_record` after changes — no orchestration code on
your side.

### Step 3: Use it from your own code

The daemon speaks MCP over HTTP, so no SDK is required:

```javascript
const call = (name, args) =>
  fetch('http://localhost:37800/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0', id: 1, method: 'tools/call',
      params: { name, arguments: args },
    }),
  })
    .then((r) => r.json())
    .then((j) => j.result.content[0].text);

await call('awareness_record', {
  action: 'remember',
  content: 'Refactored auth middleware to use JWT rotation.',
});

console.log(await call('awareness_recall', { semantic_query: 'auth middleware' }));
// Found 1 memories:
// 1. [turn_summary] Refactored auth middleware to use JWT rotation (70%, today)
```

Structured reads go over REST:

```javascript
const r = await fetch('http://localhost:37800/api/v1/memories?limit=10');
const { items, total } = await r.json();
```

Browse what has accumulated at <http://localhost:37800/>, or run
`awareness-local dashboard` to open it.

---

## Next Steps

1. **Create your Digital Twin** — initialize in your favorite IDE
2. **Use it for a real project** — let it learn your style over time
3. **Invite team members** — share your team Twin for better collaboration
4. **Explore autonomous deals** — let your agent discover opportunities via [Deal Broadcasting](#)
5. **Check your growth** — view analytics on how your Twin is improving

Learn more in [ERC-8350](#) for how Digital Twins are verified on-chain, or explore [Deal Broadcasting](#) to see how your agent can autonomously discover collaborators.