memwal-sharing

Cross-tool Walrus Memory sharing — Claude Code + Codex unified memory layer.

Preferences, architecture decisions, and bug fixes learned in one AI tool are lost when switching to another. memwal-sharing leverages Walrus Memory's owner + namespace model to make memories write once, available everywhere.

Architecture

         ┌────────────────────────────────────┐
         │     Walrus Memory Account          │
         │     (single owner identity)        │
         │                                    │
         │  project:my-app                    │
         │  ├── Memory (written by Claude)    │
         │  ├── Memory (written by Codex)     │
         │  user-preferences                  │
         │  ├── Memory (written by Claude)    │
         │  shared-context                    │
         │  ├── Memory (written by Claude)    │
         │  └── Memory (written by Codex)     │
         └──────────┬───────────┬─────────────┘
                    │           │
          ┌─────────▼───┐  ┌────▼───────────┐
          │ Claude Code │  │  Codex CLI     │
          │ read+write  │  │  read+write    │
          └─────────────┘  └────────────────┘

Quick Start

Prerequisites

• Node.js >= 18.0.0
• A Walrus Memory account (memwal-mcp login)
• Claude Code and/or Codex CLI installed

Install

# Install to both Claude Code and Codex CLI (default)
npx memwal-sharing install

# Install to a specific target
npx memwal-sharing install --target claude
npx memwal-sharing install --target codex

# Login to Walrus Memory (if not already done)
npx memwal-sharing login

# Verify connectivity
npx memwal-sharing verify

Verify Cross-Tool Sharing

# In Claude Code
> remember I prefer pnpm for all projects

# Then in Codex CLI
> what package manager do I prefer?
# → Codex recalls the memory from Walrus and answers "pnpm"

How It Works

Three-Tier Namespace Model

Recall order:   project:<repo>  →  user-preferences  →  shared-context
                (5 memories)        (3 memories)         (3 memories)

Write routing:
  preferences / themes      → user-preferences
  decisions / bugs / conventions → project:<repo>
  snapshots                 → project:<repo>
  everything else           → shared-context

Memory Storage Format

[MEM][CLAUDE] User prefers pnpm as package manager
[MEM][CODEX] [Decision] API layer uses Hono
[MEM][CLAUDE] [PROJECT:my-app] [email protected]:user/my-app.git
 ─── ──────── ───────────────────────────────────────────
  │     │                        │
  │     │                        └── semantic content
  │     └── source tool tag
  └── universal marker (recall "[MEM]" matches everything)

Hook Event Flow

| Hook | Claude Code | Codex CLI | Description | |------|-------------|-----------|-------------| | SessionStart | ✅ | ✅ | Multi-ns restore + recall, project registry, inject context | | UserPromptSubmit | ✅ | ✅ | Priority-chain semantic search across namespaces | | PostToolUse | ✅ (matcher:"memory") | — | Mirror native memory writes to Walrus | | Stop | ✅ | ✅ | Analyze transcript + route facts to namespaces | | PreCompact | ✅ | ✅ | Snapshot context to project namespace |

Idempotency

hooks are idempotent via fingerprint-based change detection:

• Restore cooldown: skip namespace restore if done within the last hour
• Fingerprint: sha256(cwd + git branch + commit) — full multi-ns recall only when the fingerprint changes
• Project registry: project markers are only written once per project
• State file: ~/.memwal/sync-state.json

Project Structure

memwal-sharing/
├── config/
│   ├── config.json              # Config template
│   └── config.schema.json       # JSON Schema
├── hooks/                       # Hook scripts (bundled to ~/.memwal/hooks/)
│   ├── session-start.ts         # SessionStart: cross-tool memory loading
│   ├── recall.ts                # UserPromptSubmit: semantic search
│   ├── flush.ts                 # Stop: analyze + auto-store
│   ├── mirror-write.ts          # CC-only: PostToolUse memory mirror
│   └── snapshot.ts              # PreCompact: context checkpoint
├── lib/                         # Shared library
│   ├── cli.ts                   # npx CLI entry point
│   ├── config.ts                # Config + MemWal client singleton
│   ├── memwal-client.ts         # Walrus Memory SDK wrapper (logged)
│   ├── namespace-router.ts      # 3-tier namespace routing + project registry
│   ├── sync-state.ts            # Fingerprint + idempotency state
│   ├── format.ts                # Memory formatting for injection
│   └── types.ts                 # TypeScript type definitions
├── scripts/                     # Standalone utilities
│   ├── inject-claude-config.ts
│   ├── inject-codex-config.ts
│   └── verify.ts
├── tests/                       # Test suites (node:test + tsx)
├── docs/                        # Design docs + test report
├── package.json
└── tsconfig.json

Configuration

{
  "owner": "0x...",
  "serverUrl": "https://relayer.memory.walrus.xyz",
  "default_namespace": "shared-context",
  "tool_tagging": true,
  "recall": {
    "maxMemories": 8,
    "minRelevance": 0.3,
    "maxDistance": 0.7,
    "dedup_identical": true
  },
  "capture": {
    "autoSaveEveryTurns": 3,
    "signalExtraction": true,
    "signalKeywords": ["decided", "prefer", "convention", "pattern"]
  },
  "namespaces": {
    "default": "shared-context",
    "projectPrefix": "project",
    "recall": {
      "order": ["project:auto", "user-preferences", "shared-context"],
      "perNamespaceLimit": { "project:auto": 5, "user-preferences": 3, "shared-context": 3 },
      "dedupAcrossNamespaces": true
    },
    "writeRouting": {
      "preference": "user-preferences",
      "decision": "project:auto",
      "bug": "project:auto",
      "convention": "project:auto",
      "snapshot": "project:auto",
      "default": "shared-context"
    }
  }
}

Observability

Every Walrus Memory interaction is logged to stderr with the [memwal:*] prefix, visible in Claude Code and Codex CLI hook output:

[memwal:route]    recall order: project:my-app → user-preferences → shared-context
[memwal:restore]  OK namespace="shared-context" restored=0 skipped=33 (4935ms)
[memwal:recall]   OK namespace="user-preferences" results=1 returned=1 (679ms)
[memwal:recall]     · d=0.477 "[MEM][CLAUDE] User prefers pnpm"
[memwal:remember] OK namespace="user-preferences" id=abc... blob_id=def... (28441ms)
[memwal:analyze]  OK factCount=3 jobIds=3 (15600ms)
[memwal:health]   OK version=0.1.0 mode=production (4176ms)

Conflict Handling

| Scenario | Resolution | |----------|-----------| | Concurrent writes | Walrus-native — each remember() creates an independent blob | | Duplicate memories | dedup_identical: true, filtered by distance < 0.25 | | Contradictory memories | Higher recency wins; source tool + timestamp annotated for LLM judgment | | Stale memories | Newer memories get recency boost, ranking higher in semantic search |

Extending to More Tools

The same architecture works for any MCP-compatible AI tool:

~/.memwal/               # Shared memory layer
~/.claude/settings.json  # Claude Code
~/.codex/hooks.json      # Codex CLI
~/.cursor/mcp.json       # Cursor

Each tool only needs to point to the same ~/.memwal/hooks/*.js scripts.

Commands

npx memwal-sharing install                 # Install hooks + inject config (claude,codex)
npx memwal-sharing install --target claude # Claude Code only
npx memwal-sharing install --target codex  # Codex CLI only
npx memwal-sharing login                   # Authenticate with Walrus Memory
npx memwal-sharing verify                  # Run connectivity checks

Development

npm install          # Install dependencies
npm run build        # Build with tsup
npm test             # Run test suite (node:test + tsx)

License

MIT